====== runcommand Plugin ======

---- plugin ----
description: Execute a program on the fly and show its output
author     : Alessandro Celli
email      : aelsantex[at]gmail.com
type       : Syntax
lastupdate : 2014-04-01
compatible : Binky, !Hogfather, Greebo
depends    : 
conflicts  : 
similar    : 
tags       : command, program, jquery
sourcerepo : https://github.com/aelsantex/runcommand
bugtracker : https://github.com/aelsantex/runcommand/issues
downloadurl: https://github.com/aelsantex/runcommand/archive/master.zip

----

===== Description =====
This plugin executes a program on the fly and shows its output.

You can use it to generate reports from the system or to execute some administration steps.

For example, I use it to collect information from my enterprise servers (free space on disks, hardware status, etc.)



===== News =====

  * //1 Apr 2014//: New version released. This version is compatible with Binky or higher. 

===== Installation =====

==== Plugin Installation ====

Download and install the plugin using the [[plugin:extension|Extension Manager]]. 

Alternatively, refer to [[:Plugins]] on how to install plugins manually. If you want install manually follow this procedure:

  - Download the zip file from github: [[https://github.com/aelsantex/runcommand/archive/master.zip]].
  - Copy the master.zip file into Dokuwiki plugins dir.
  - unzip master.zip
  - rename the extracted folder from runcommand-master to runcommand.
  - give the right permission (755 on linux) and owner (maybe www-data on linux).

==== Script directory ====

Create a directory under DOKUWIKI_ROOT folder and set it into **script_dir** field of runcommand section under wiki configuration page. 
As default, I choose to set DOKUWIKI_ROOT/data/scripts directory. See [[#configuration|configuration]] for more details.
===== Syntax =====

To fix some old limits and to give a most pratical support with new objects I broke the compatibility with the old syntax.

This is the new grammar for runcommand plugin:

==== Grammar ====

  <runcommand>
  command|<command> 
  outputType|{ choice | text | wiki | html | binary }
  runButtonText|<run button label> 
  cancelButtonText|{ <cancel button label> | none } 
  [ <arg1 name>|<arg1 label>|<<flags>>|<<arguments>> ] 
  ...
  [ <argN name>|<argN label>|<<flags>>|<<arguments>> ] 
  </runcommand> 
  
  <<flags>> ::= [ newline ] [ , <<flags>> ]
  
  <<arguments>> ::= {
    hidden=<fixed value> |
    list=<item 1 (default)>:<label 1>;[<item N>:<label N>;] |
    text=<default value> |
    autocomplete=<item 1>;[<item N>;] |
    slider=min:<min value>;max:<max value>;value:<default value>;step:<step value>; |
    spinner=min:<min value>;max:<max value>;value:<default value>; |
    date=[format:<date format>] |
  }
  


==== How to use ====

Syntax is simple:

**<runcommand>**\\
**command|**//<command>// \\
**outputType|**//<output type>// \\
//runButtonText|<run button label>// \\
//cancelButtonText|{ <cancel button label> | none }// \\
//<arg1 name>//**|**//<arg1 label>//**|**[//newline//]**|**<arg1 type>=//<argument options 1>// \\
... \\
//<argN name>//**|**//<argN label>//**|**[//newline//]**|**<argN type>=//<argument options N>// \\
**</runcommand>** \\


//**Where:**//

  * **<command>**: The command invocation. You can use the same syntax used into a CLI interface to run the program. You can pass some arguments and keep argument values from runcommand arguments. The arguments are referred by the arg name preceded by dollar char (**$**). No space are accepted in the arg name. \\
See [[#configuration|configuration]] for security details.

  * **<output type>**: One of the next values:
    * **text**: If the program writes its output in text format.
    * **html**: If the program writes its output in HTML format.
    * **wiki**: If the program writes its output in DokuWiki format (output is rendered before its visualizations).
    * **choice**: The user may choose one of the previous formats from a select field.

  * **<arg-X name>**: It is used as the command argument name preceded by dollar char (**$**).

  * **<arg-X label>**: The label is printed before the argument field.

  * **<arg type>**: One of the next values:
    * **text**: If you want a text field for the argument.
    * **hidden**: Generate a hidden field. If you use a hidden field, the label isn't printed.
    * **list**: Generate a selectable list of values.
    * **autocomplete**: Generate an autocomplete text field.
    * **slider**: Generate a slider with given minimum and maximum value.
    * **spinner**: Generate a spinner field with the given minimum and maximum value.
    * **date**: Generate a date field; the uses may be specify the date format.

  * **<argument options X>**: Is specific for all field type.
    * **hidden**: Fixed value associated to this argument.
    * **text**: The default value for this text field
    * **list**: The list of available values for a list field.
    * **autocomplete**: The list of autocomplete value for this text field.
    * **slider**: Require the minimum, maximum, default value and step value.
    * **spinner**: Require the minimum, maximum and default value.
    * **date**: May be specified the date output format.


==== Example ====

In this example, I use the printf command to show the values of arguments.

  <runcommand>
  command|printf "==== $arg_text ====\\n  * valorelista: $arg_list \\n  * Autocomp: $arg_autocomp \\n  * arg_slider: ** $arg_slider ** \\n  * Spinner: $arg_spinner \\n  * Data: $arg_date \\n------- "
  outputType|choice
  runButtonText|Esegui 
  cancelButtonText|Cancella
  arg_text|Test text|newline|text=default text
  arg_list|Test list|newline|list=item 1:List item1;item 2:List item2;item 3:List item3;
  arg_autocomp|Test autocomplete|newline|autocomplete=ActionScript;Apple Script;Asp;BASIC;C;C++;Clojure;COBOL;ColdFusion;Erlang;Fortran;Groovy;Haskell;Java;Java script;Lisp;Perl;PHP;Python;Ruby;Scala;Scheme;
  arg_slider|Test slider|newline|slider=min:0;max:100;value:30;step:10;
  arg_spinner|Test spinner|newline|spinner=min:0;max:20;value:7; 
  arg_date|Test date|newline|date=format:mm dd yy
  </runcommand>

{{https://raw.githubusercontent.com/aelsantex/public_images/master/runcommand_example1.png}}

In this example I use the printf command to show the values of arguments without display the cancel button and with custom label for run button. The fields are not on newline.

  <runcommand>
  command|sleep 1 ; printf "==== Test 2 ====\\n==== $arg_text ====\\n  * valorelista: $arg_list \\n  * Autocomp: $arg_autocomp \\n  * arg_slider: ** $arg_slider ** \\n  * Spinner: $arg_spinner \\n  * Data: $arg_date \\n------- "
  outputType|choice
  runButtonText|Esegui 
  cancelButtonText|Cancella
  arg_text|Test text|newline|text=default text
  arg_list|Test list||list=item 1:List item1;item 2:List item2;item 3:List item3;
  arg_autocomp|Test autocomplete||autocomplete=ActionScript;Apple Script;Asp;BASIC;C;C++;Clojure;COBOL;ColdFusion;Erlang;Fortran;Groovy;Haskell;Java;Java script;Lisp;Perl;PHP;Python;Ruby;Scala;Scheme;
  arg_slider|Test slider|newline|slider=min:0;max:100;value:30;step:10;
  arg_spinner|Test spinner||spinner=min:0;max:20;value:7; 
  arg_date|Test date||date=
  </runcommand>

{{https://raw.githubusercontent.com/aelsantex/public_images/master/runcommand_example2.png}}

===== Configuration ===== 

From wiki configuration's page you find four fields dedicated to runcommand.

  * **safe_scripts**: If this is checked, the program must be in the //script_dir// directory. I suggest to keep it checked for security reason. Think about an **rm -rf /** command.... 8-o

  * **script_dir**: specify the directory where the programs are located. As a convention, I suggest using folder **scripts** under **DOKUWIKI_ROOT/data** directory.

  * **debug_level**: Enable the debug of syntax page. 0 No debug, 3 max debug.

  * **rc_default_dateformat**: Specify the default date format for the date field.

===== Languages support ===== 

Actually, runcommand supports only Italian and English languages and partially French.
I'm really happy if anyone could contribute to the translation in other languages... ;)

===== Bugs ===== 

Write here if you find a bug.

2020.09.22 This Plugin stopped working with the release of the Dokuwiki "Hogfather" release. If this plugin is active with "Hogfather", there will be a blank screen appearing.
===== Discussion ===== 

<nowiki>
Hi, I can't get this plugin to work. 
I've created the /data/scripts directory and generated a listfiles.sh file (chmod 755)
Even the example code doesn't work. It keeps showing the "Please Wait..." gif.
Any ideas?
</nowiki>


<nowiki>
Same problem here, did all the above steps and getting 'Please wait...' and then nothing.
</nowiki>