Difference: TWikiScripts (3 vs. 4)

Revision 42007-01-13 - 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.

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.

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:

from browser https://wiki.caida.org/twiki/bin/statistics updates all user webs
from browser https://wiki.caida.org/twiki/bin/statistics?webs=TWiki,Main,Sandbox updates TWiki,Main,Sandbox
from browser https://wiki.caida.org/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.

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`

View topic | History: r17 < r16 < r15 < r14 | More topic actions...

Copyright © 1999-2025 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.