DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== 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-03-31
compatible : Binky
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 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|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.

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

{{http://aelsantex.googlepages.com/runcommand2.jpeg|}}
===== 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.... 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.

* **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:
  * <del>Hard coded path in ''postaction.php''</del> FIXED !
  * 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 =====

* --- //[[emauvaisfr@yahoo.fr|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**<code 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&eacute;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.';
</code>
    * **fr/settings.php**<code 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&eacute;cuter que les scripts pr&eacute;sents dans le dossier des scripts autoris&eacute;s.';
$lang['script_dir']  = 'Dossier qui contient les scripts autoris&eacute;s (&agrave; partir de la racine du dokuwiki).';
</code>

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:

<file bash printf>
#!/bin/bash
 printf "$*\n"
</file>

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 [[plugin:searchtablejs|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

Please fill all the letters into the box to prove you're human. T L O W P Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International