Difference: TWikiScripts (3 vs. 4)

Revision 413 Jan 2007 - Main.TWikiContributor

Line: 1 to 1
 

TWiki CGI and Command Line Scripts

Line: 14 to 14
 

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

Changed:
<
<
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"
Changed:
<
<
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:
Line: 51 to 51
 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

Changed:
<
<
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:
Line: 67 to 67
 
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.  
Added:
>
>
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.
  1. 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.
Line: 188 to 189
 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

Changed:
<
<
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.
 
Added:
>
>
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"
Changed:
<
<
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.

ALERT! 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

Line: 202 to 207
  http://my.host/bin/rest/<subject>/<verb>
Changed:
<
<
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.
Line: 212 to 215
  Call the Plugin
Changed:
<
<
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.

Parameter Description Default
Changed:
<
<
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.  
Line: 239 to 240
 
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.  
Added:
>
>
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.
Line: 298 to 302
 
webs comma-separated list of webs to run stats on all accessible webs
logdate YYYYMM to generate statistics for current month
Added:
>
>
for example:
  1. from browser http://www.twiki.ufba.br/twiki/bin/statistics updates all user webs
  2. from browser http://www.twiki.ufba.br/twiki/bin/statistics?webs=TWiki,Main,Sandbox updates TWiki,Main,Sandbox
  3. from browser http://www.twiki.ufba.br/twiki/bin/statistics/TWiki updates TWiki
  4. from command line twiki/bin/statistics updates all user webs
  5. from command line twiki/bin/statistics -webs=TWiki,Main,Sandbox updates TWiki,Main,Sandbox
  6. 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.
Line: 321 to 335
 
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.  
Added:
>
>
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.  
Line: 342 to 357
 

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

 
This site is powered by the TWiki collaboration platformCopyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiScripts