runcommand Plugin

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.)

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

Download and install the plugin using the Extension Manager.

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

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

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 for more details.

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:

<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>] |
}

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 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.

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>

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>

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….

• 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.

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… ;)

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.

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?

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