This is an old revision of the document!
Table of Contents
runcommand plugin
Compatible with DokuWiki
Binky
This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.
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 Manager using the URL given above.
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 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>] | }
Download and Installation
It's quite easy:
- download this archive and unpack it in the /lib/plugins directory of your wiki or use the plugin manager page from admin menu (URL: https://sites.google.com/site/aesantex/runcommand.zip?attredirects=0).
- Create directory scripts under wiki installation and set it into script_dir field of runcommand section under wiki configuration page. As the default, I choose to put dir under DOKUWIKI_ROOT/data/scripts. See configuration for more details.
How to use
Syntax is simple:
<runcommand>
command|<command>
outputType|<output type>
runButtonText|<run button label>
cancelButtonText|{ <cancel button label> | none }
<arg-1 label>|<arg type>=<arg value>
…
<arg-n label>|<arg type>=<arg value>
</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. Keep in mind that the arguments are referred by its label preceded by dollar char ($) and the space substituted with underscore (see next example, refer $arg_1 into command, it matches with <arg-1 label> arg 1). 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 label>: The label is printed before the argument field and the name of the argument for it is used as the command argument.
- <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.
- <arg value>: The default value for a text and an hidden field. The list of available value for a list. If you use a list you must respect this syntax:
list=<item 1>:label 1;<item N>:<label N>
Where:- <item X>: Is the value given by the list as argument.
- <label X>: Is the label that the user sees in the list.
Example:
In this example, I use the printf command to show the values of arguments.
<runcommand> command|printf "==== Test ====\n\n__Result__\n\n * arg1=**$arg_1**\n * arg2=//$arg_2//\n * arg3=$arg_3\n\n <note>Work</note>" cancelButtonText|{ <cancel button label> | none } arg 1|text=argument 1 arg 2|hidden=argument 2 arg 3|list=item 1:value 1;item 2:value 2;item 3:value 3;default:item 2 </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
<runcommand> command|printf "==== Test ====\n\n__Result__\n\n * arg1=**$arg_1**\n * arg2=//$arg_2//\n * arg3=$arg_3\n\n <note>Work</note>" runButtonText|Test Me cancelButtonText|none outputType|wiki arg 1|text=argomento 1 arg 2|text=argomento 2 arg 3|list=item 1:value 1;item 2:value 2;item 3:value 3;default:item 2 </runcommand>
Runcommand before command execution
Runcommand after command execution
Configuration
From wiki configuration's page you find five 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.
- syntax_debug: Enable the debug (you can choice 4 level of debug) of syntax page.
- postaction_debug: Enable the debug (you can choice 4 level of debug) of postaction page. May be help for debug external command execution
- debug_log: File,with full path, where write the debug messages.
Languages support
Actually, runcommand supports only Italian and English languages. I'm really happy if anyone could contribute to the translation in other languages… ;)
Bugs
Write here if you find a bug.
Some points to consider:
Hard coded path inFIXED !postaction.php
- If you are using RewriteRules in Apache, or some other settings that convert slashes into underscores, the postaction.php scrip may not get called. → Yes, but is necessary to use the space into label, a possible solution may be dissociate the label from the name of the argument, but this choice increase the difficult of plugin syntax.
- Ensure that CSS and JavaScript compression is off when using jQuery.
– Chris Usher
Discussion
- — Etienne M. 25/03/2009 11:27 Hi! Not sure I will use your plugin, but here are the french language files:
- fr/lang.php
<?php /** * French language file * * @author Alessandro Celli <aelsantex@gmail.com> * @author Etienne M. <emauvaisfr@yahoo.fr> */ // custom language strings for the plugin $lang['btn_submit'] = 'Exécuter'; $lang['btn_reset'] = 'Effacer'; $lang['lbl_outputFormat'] = 'Format de sortie '; $lang['fld_text'] = 'Texte'; $lang['fld_wiki'] = 'Wiki'; $lang['fld_html'] = 'Html'; $lang['msg_wrongsyntax'] = 'Mauvaise syntaxe pour le plugin runcommand.';
- fr/settings.php
<?php /** * French language file * * @author Alessandro Celli <aelsantex@gmail.com> * @author Etienne M. <emauvaisfr@yahoo.fr> */ // for the configuration manager $lang['safe_scripts'] = 'N\'exécuter que les scripts présents dans le dossier des scripts autorisés.'; $lang['script_dir'] = 'Dossier qui contient les scripts autorisés (à partir de la racine du dokuwiki).';
Hi Etienne, many thanks, I have included your translation but now I have introduced other 3 parameters. Can you help me to translate that?
- — Mailgifson
Can you give a simple script to test?
I can not use this plug-in :S
Ok, a little example for linux/unix users.. Save the follow script into scripts directory as printf with execution permissions (rwxr–r–) and try to use given examples:
- printf
#!/bin/bash printf "$*\n"
Hello! Thanks for the plugin: it's been quite useful! I'd like to upgrade it, but the download link is broken :(
- — Anonymous 31/07/2013 17:46 Hello, good plugin, but it conflicts with searchtablejs plugin in Weatherwax release
- I do some tests with this plugin for the next release.
- — Fravadona 09/09/2013 16:01 Hello, I can't get it work with WeatherWax; it gives me a syntax error with your examples. Do I need to install JQuery which is obsolete on the actual version of Dokuwiki ?
- I'm sorry, new version of plugins fix this problem, please wait for it!
In Windows 7 Plugin to work, you must create the folder c:\tmp