| |
TWiki CGI and Command Line Scripts |
| | CGI environment
In the CGI environment parameters are passed to the scripts via the URL and URL parameters. Environment variables are also used to determine the user performing the action. If the environment is not set up, the default TWiki user is used (usually guest).
Command-line |
|
<
< | You must be cd'd to the twiki/bin directory to run the scripts from the command line. To avoid issues with file permissions, run the scripts as the web server user such as nobody or www. |
>
> | You must be have the twiki/bin directory on the perl path to run the scripts from the command line. To avoid issues with file permissions, run the scripts as the web server user such as nobody or www. |
| | Parameters are passed on the command line using '-name' - for example,
$ cd /usr/local/twiki/bin
$ save -topic MyWeb.MyTopic -user admin -action save -text "New text of the topic"
|
|
<
< | All parameters require a value. |
>
> | All parameters require a value, even if that is the empty string. |
| | Common parameters
All the scripts accept a number of common parameters. The first two components of the URL after the script name are taken as the web and the topic, respectively. Standard URL parameters are: |
| | NOTE: The result from changes script and the topic WebChanges can be different, if the changes file is deleted from a web. In particular, in new installations the changes script will return no results while the WebChanges topic will.
configure |
|
<
< | configure is the browser script used for inspection and configuration of the TWiki configuration. None of the parameters to this script are useable for any purpose except configure. |
>
> | configure is the browser script used for inspection and configuration of the TWiki configuration. None of the parameters to this script are useable for any purpose except configure. See configure. |
| | edit
The edit scipt understands the following parameters, typically supplied by HTML input fields: |
| |
contenttype | Optional parameter that defines the application type to write into the CGI header. Defaults to text/html. May be used to invoke alternative client applications | |
anyname | Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}%, it will be replaced by its value | |
breaklock | If set, any lease conflicts will be ignored, and the edit will proceed even if someone is already editing the topic. | |
|
|
>
> |
redirectto | If the user continues from edit to save, and if the save process is successful, save will redirect to this topic or URL. The parameter value can be a TopicName, a Web.TopicName, or a URL.
Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl}). | |
|
| | Form field values are passed in parameters named 'field' - for example, if I have a field Status the parameter name is Status.
- The first sequence of ten or more
X characters in the topic name will be converted on save to a number such that the resulting topic name is unique in the target web.
|
| | BulkRegistration provides the means to create multiple accounts but it does not announce those accounts to the users who own them. BulkResetPassword is used to assign the passwords, the Introduction is used to explain why they are receiving the mail.
rest |
|
<
< | This REST (Representational State Transfer) script can be invoked via http in a similar way as the view script (see Invocation Examples, below) to execute a function that is associated to a "subject" and a "verb" (see below). It'll print the result directly to the stream unless the endPoint parameter is specified, in which case the control is redirected to the given topic.
The rest script itself uses one parameter: |
>
> | This REST (Representational State Transfer) script can be invoked via http in the same way as the other TWiki scripts (see Invocation Examples, below) to execute a function that is associated to a "subject" and a "verb" (see below). These functions are usually registered by plugins using the TWiki::Func::registerRESTHandler method. The rest script will print the result directly to the browser unless the endPoint parameter is specified, in which case it will output a redirect to the given topic. |
| | |
|
>
> | The rest script supports the following parameters:
username | If TemplateLogin, or a similar login manager not embedded in the web server, is used, then you need to pass a username and password to the server. The username and password parameters are used for this purpose. |
password | See username |
topic | If defined as the full name (including web) of a topic, then when the script starts up plugins will be passed this as the "current" topic. If not defined, then %USERWEB%.WebHome will be passed to plugins. |
|
| |
endPoint | Where to redirect the response once the request is served, in the form "Web.Topic" |
|
|
<
< | Any additional parameters are passed directly to the function (i.e: The function can get any other parameter using the CGI $query object) |
>
> | The function is free to use any other query parameters for its own purposes.
 The rest script should always require authentication in any TWiki that has logins. Otherwise there is a risk of opening up major security holes. So make sure you add it to the list of authenticated scripts if you are using ApacheLogin. |
| | Invocation Examples |
| | http://my.host/bin/rest/<subject>/<verb> |
|
<
< | where <subject> must be the WikiWord name of one of the installed TWikiPlugins, and the <verb> is the alias for the function registered using the registerRESTHandler. The <subject> and <verb> are then used to lookup and call the registered function.
Functions outside the Plugins also can be registered, but please consider the security implications of allowing URL access, as functions can sidestep TWiki Authentication & Authorisation settings. |
>
> | where <subject> must be the WikiWord name of one of the installed TWikiPlugins, and the <verb> is the alias for the function registered using the TWiki::Func::registerRESTHandler method. The <subject> and <verb> are then used to lookup and call the registered function. |
| | <subject> and <verb> are checked for illegal characters exactly in the same way as the web and topic names. |
| | Call the Plugin |
|
<
< | You can also call the function from the command line, but this will be run as the TWikiAdminGroup (as it is assumed that shell access is secure) - eg: ./rest EmptyPlugin.example
Note that for calls to Plugins, they must be enabled in configure. |
>
> | Note that for Plugins to register REST handlers, they must be enabled in configure. |
| | save
The save script performs a range of save-related functions, as selected by the action parameter.
|
|
<
< |
action_save=1 | default; save, return to view, dontnotify is OFF | |
action_quietsave=1 | save, and return to view, dontnotify is ON | |
action_checkpoint | save and redirect to the edit script, dontnotify is ON | |
|
>
> |
action_save=1 | default; save, return to view, dontnotify is off | |
action_quietsave=1 | save, and return to view, dontnotify is on | |
action_checkpoint | save and redirect to the edit script, dontnotify is on | |
|
| |
action_cancel | exit without save, return to view | |
action_preview | preview edited text | |
action_addform | Redirect to the "change form" page. | |
|
| |
formtemplate | if defined, use the named template for the form | |
editaction | When action is checkpoint, add form or replace form..., this is used as the action parameter to the edit script that is redirected to after the save is complete. | |
originalrev | Revision on which the edit started. | |
|
|
>
> |
edit | The script to use to edit the topic when action is checkpoint | edit |
editparams | The parameter string to use to edit the topic | |
redirectto | The save process will redirect to this topic or URL if it is successful. (Typically this would be the URL that was being viewed when edit was invoked). The parameter value can be a TopicName, a Web.TopicName, or a URL.
Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl}). | view topic being edited |
|
| | Any errors will cause a redirect to an oops page. |
| |
webs | comma-separated list of webs to run stats on | all accessible webs |
logdate | YYYYMM to generate statistics for | current month |
|
|
>
> | for example:
- from browser http://92337.wcapt.asia/twiki/bin/statistics updates all user webs
- from browser http://92337.wcapt.asia/twiki/bin/statistics?webs=TWiki,Main,Sandbox updates TWiki,Main,Sandbox
- from browser http://92337.wcapt.asia/twiki/bin/statistics/TWiki updates TWiki
- from command line twiki/bin/statistics updates all user webs
- from command line twiki/bin/statistics -webs=TWiki,Main,Sandbox updates TWiki,Main,Sandbox
- from command line twiki/bin/statistics TWiki.WebHome updates TWiki
see TWikiSiteTools#WebStatistics_site_statistics for updating statistics using cron. |
| | twiki
Single-script interface to the functionality of all the other scripts. Experimental, not for production use. Read the code if you want to know more. |
| |
raw=debug | As raw=on, but also shows the metadata (forms etc) associated with the topic. | |
raw=text | Shows only the source of the topic, as plain text (Content-type: text/plain). Only shows the body text, not the form or other meta-data. |
raw=all | Shows only the source of the topic, as plain text (Content-type: text/plain), with embedded meta-data. This may be useful if you want to extract the source of a topic to a local file on disc. | |
|
|
>
> |
section | Allows to view only a part of the topic delimited by a named section (see VarSTARTSECTION). If the given section is not present, no topic content is displayed. | |
|
| |
contenttype | Allows you to specify a different Content-Type: (e.g. contenttype=text/plain) | |
rev | Revision to view (e.g. rev=45) | |
template | Allows you to specify a different skin template, overriding the 'view' template the view script would normally use. The default template is view. For example, you could specify /twiki/bin/view/TWiki/TWikiScripts?template=edit. This is mainly useful when you have specialised templates for a TWiki Application. | |
|
| | geturl.pl
This is a very simple script to get the content of a web site. It is marked as deprecated and might be removed (or enhanced) in a future TWiki release. Its functions are covered by the standard wget and curl commands. |
|
<
< |
- Usage:
geturl <host> <path> [<port> [<header>]]
- Example:
geturl some.domain /some/dir/file.html 80
|
>
> |
- Usage:
geturl.pl <host> <path> [<port> [<header>]]
- Example:
geturl.pl some.domain /some/dir/file.html 80
|
| |
- Will get:
http://some.domain:80/some/dir/file.html
rewriteshebang.pl |