Difference: TWikiScripts (15 vs. 16)

Revision 162015-07-07 - TWikiContributor

Line: 1 to 1

TWiki CGI and Command Line Scripts

Line: 8 to 8

Added:

>
>

CGI Scripts

Details on CGI scripts located in the twiki/bin directory.

Added:

>
>

General Information

Added:

>
>

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).

Added:

>
>

Command-line

You must 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.

Line: 25 to 29

Parameters are passed on the command line using '-name' - for example,

$ cd /usr/local/twiki/bin

Changed:

<
< $ save -topic MyTopic -user admin -action save -text "New text of the topic"

>
> $ save -topic MyTopic -user admin -method POST -action save -text "New text of the topic"

All parameters require a value, even if that is the empty string.

Added:

>
>

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:

Parameter	Description	Default
`topic`	If this is set to a URL, TWiki will immediately redirect to that URL. Otherwise it overrides the URL and is taken as the topic name (you can pass Web.TopicName)

Changed:

<
<

user Command-line only; set the name of the user performing the action. Note: this usage is inherently insecure, as it bypasses webserver login constraints. For this reason only authorized users should be allowed to execute scripts from the command line.

>
>

`user`	Command-line only; set the name of the user performing the action. Note: this usage is inherently insecure, as it bypasses webserver login constraints. For this reason only authorized users should be allowed to execute scripts from the command line.	`TWikiAdminGroup`
`method`	Commad-line only; set the HTTP request method. Some scripts requires the POST method under certain circumstances. In such a case, you need to specify the POST method to run the script from a command line.	`GET`

`skin`	Overrides the default skin path (see TWikiSkins)
`cover`	Specifies temporary skin path to prepend to the skin path for this script only (see TWikiSkins)

Added:

>
>

`attach`

Despite the name, this script doesn't actually attach a file to a topic - for that, use upload. This script is part of the transactions sequence executed when a file is uploaded from the browser. it just generates the "new attachment" page for a topic.

Line: 46 to 53

Parameter	Description	Default
`filename`	Name of existing attachment (if provided, this is a "manage attachment" action)	none (in which case this is a "new attachment" action)

Added:

>
>

`changes`

Shows all the changes in the given web.

Line: 59 to 67

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.

Added:

>
>

`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.

Added:

>
>

`edit`

The edit script understands the following parameters, typically supplied by HTML input fields:

Line: 87 to 97

Note: Most skins support the definition of EDIT_SKIN, which is used as the value of the cover parameter in edit URLs. This allows you to override the default edit skin on a web, topic or user basis.

Added:

>
>

`login`

Used for logging in when TWiki login is being used (e.g TemplateLoginManager).

Line: 95 to 106

`username`	username of user logging in	none
`password`	password of user logging in	none

Added:

>
>

`logon`

Used for logging in when Web Server authentication is being used (e.g. ApacheLoginManager). The script does nothing; it is purely a placeholder for triggering the login process. The webserver will be set up to require a valid user to access this script, thus triggering the webserver login process.

Added:

>
>

`manage`

Performs a range of management functions.

Line: 107 to 120

Note: The manage script can only be called via http POST method for createweb renameweb, and deleteUserAccount.

Added:

>
>

`action=createweb`

Parameter	Description	Default

Line: 116 to 130

`sitemapwhat`	Value for SITEMAPWHAT	''
`nosearchall`	Value for NOSEARCHALL	''

Added:

>
>

`action=renameweb`

Parameter	Description	Default

Line: 123 to 138

`newparentweb`	New parent web name	''
`confirm`	If defined, requires a second level of confirmation. Supported values are "getlock", "continue", and "cancel"	''

Added:

>
>

`action=editSettings`

No parameters

Added:

>
>

`action=saveSettings`

Parameter	Description	Default

Line: 135 to 152

redirectto If the savesettings 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 (Security setup > Miscellaneous {AllowRedirectUrl}).

All other parameters may be interpreted as form fields, depending on the current form definition in the topic.

Added:

>
>

`action=bulkRegister`

See BulkRegistration.

Line: 143 to 161

`EmailUsersWithDetails`	Whether to mail registered users or not	false
`LogTopic`	Topic to save the log in	Same as topic name, with 'Result' appended.

Added:

>
>

`action=changePassword`

Change password, email address, or both, of a user.

Line: 154 to 173

email new email address none

password, =passwordA and email are optional. If neither or password and passwordA is set, then the user password is left unchanged. If email is unset, their email is left unchanged.

Added:

>
>

`action=resetPassword`

Reset the password for a single or multiple users

Line: 165 to 185

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.

Added:

>
>

`action=deleteUserAccount`

Unregisters (removes) the currently logged-in user.

Parameter	Description	Default
`password`	Users' password	none

Added:

>
>

`oops`

This script is mainly used for rendering pages containing error messages, though it is also used for some functional actions such as manage pages (move topic etc).

Line: 184 to 206

`def`	Optional, can be set to the name of a single definition within `template`. This definition will be instantiated in the `template` wherever `%INSTANTIATE%` is seen. This lets you use a single template file for many messages. For an example, see `oopsmanagebad.tmpl`.
`paramN`	Where N is an integer from 1 upwards. These values will be substituted into `template` for `%PARAM1%` etc.

Added:

>
>

`preview`

This script is deprecated. Its functions are covered by the save script.

Added:

>
>

`rdiff`

Renders the differences between version of a TWiki topic

Line: 201 to 225

TODO:

add a {word} render style

Added:

>
>

`register`

Parameter	Description	Default

Line: 209 to 234

Note: The register script can only be called via http POST method, not GET. Make sure to specify the "post" method if you call the register script via a form action.

Added:

>
>

`rename`

Used for renaming topics and attachments.

Line: 227 to 253

Note: The rename script can only be called via http POST method, not GET. Make sure you specify method="post" if you call the rename script via a form action.

Added:

>
>

`copy`

Used for copying the current topic in its entirety including its history and attachments.

Line: 239 to 266

`overwrite`	By default, copy does not happen if the destination topic already exists. If this parameter is `'on'`, the destination topic is deleted if exists before copying takes place	`off` (no overwrite)
`disablefixlinks`	Bypass fixing WikiWord links in the copy destination topic if copy is done across webs. Fixing links in the copied topic such as from SomeLink to Otherweb.SomeLink is usually desirable so that links in the copied topic still point to the same target	`off` (links are fixed)

Added:

>
>

`mdrepo`

Used to retrieve and update data in MetadataRepository. Please read MetadataRepository and MetadataRepository.

Added:

>
>

`rest`

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.

Line: 274 to 303

Note that for Plugins to register REST handlers, they must be enabled in configure.

Added:

>
>

`save`

The save script performs a range of save-related functions, as selected by the action parameter.

Line: 332 to 362

It is not possible to call save from an <a href=""> link.

Added:

>
>

`search`

CGI gateway to the %SEARCH% functionality driven by the following CGI parameters:

Line: 339 to 370

Parameter:	Description:	Default:
`"text"`	Search term. Is a keyword search, literal search or regular expression search, depending on the `type` parameter. SearchHelp has more	required
`search="text"`	(Alternative to above)	N/A

Changed:

<
<

web="Name"
web="Main, Know"
web="all" Comma-separated list of webs to search. See TWikiVariables for more details. Current web

>
>

web="Name"
web="Main, Know"
web="all" Comma-separated list of webs to search. See VarSEARCH for more details. Current web

`topic="WebPreferences"` `topic="*Bug"`	Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma.	All topics in a web
`excludetopic="Web*"` `excludetopic="WebHome, WebChanges"`	Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma.	None
`type="keyword"` `type="literal"` `type="regex"`	Do a keyword search like `soap "web service" -shampoo`; a literal search like `web service`; or RegularExpression search like `soap;web service;!shampoo`	`%SEARCHVAR- DEFAULTTYPE%` preferences setting (literal)

Line: 363 to 394

`nofinalnewline="on"`	If `on`, the search variable does not end in a line by itself. Any text continuing immediately after the search tag on the same line will be rendered as part of the table generated by the search, if appropriate.	`off`
`separator=", "`	Line separator between hits	Newline `"$n"`

Added:

>
>

`statistics`

Refresh the WebStatistics topics in range of webs.

Line: 381 to 413

See TWikiSiteTools for updating statistics using cron.

Added:

>
>

`upload`

Uploads an attachment to a topic. The HTTP request is expected to be in multipart/form-data format.

Parameter	Description	Default

Changed:

<
<

`hidefile`	if defined, will not show file in attachment table
`filepath`	local (client) path name of the file being uploaded. This is used to look up the data for the file in the HTTP query.
`filename`	deprecated, do not use

>
>

`hidefile`	If defined, will not show file in attachment table
`filepath`	Local (client) path name of the file being uploaded. This is used to look up the data for the file in the HTTP query.
`filename`	Deprecated, do not use

filecomment Comment to associate with file in attachment table

Changed:

<
<

`createlink`	if defined, will create a link to file at end of topic
`changeproperties`	if defined, this is a property change operation only - no file will be uploaded.	null
`updatefield`	If defined and if the value matches the name of a form field, it will update that form field with the name of the uploaded file.

>
>

`createlink`	If defined, will create a link to file at end of topic
`changeproperties`	If defined, this is a property change operation only - no file will be uploaded.	null
`updatefield`	If defined and if the value matches the name of a form field, it will update that form field with the format defined by the `updateformat` parameter.
`updateformat`	Format of the value of the form field indicated by the `updatefield` parameter. The default is the name of the attached file, but can be set to include more, such as the path to the image, `%PUBURL%/%BASEWEB%/%BASETOPIC%/$filename`.	`$filename`

You can use a tool like curl to upload files from the command line using this script.

Note: The upload script can only be called via http POST method, not GET.

Added:

>
>

`view`

Used for viewing topics.

Line: 424 to 459

which shows the topic as plain text; useful for those who want to download plain text for the topic. Using skin=text this way is DEPRECATED, use raw=text instead.

Added:

>
>

`viewfile`

Used for viewing attachments. Normally, a site will publish the attachments (pub) directory using a URL. However if it contains sensitive information, you will want to protect attachments using TWikiAccessControls. In this case, you can use the viewfile script to give access to attachments while still checking access controls.

Line: 431 to 467

Parameter	Description	Default
`filename`	name of attachment
`rev`	Revision to view

Added:

>
>

debug Put debug info to the debug log

Instead of using the filename parameter, you can append the attachment name to the end of the URL path (after the topic) e.g. https://eso.org/projects/alma/arc/tw/bin/viewfile/Webname/TopicName/Attachment.gif

Added:

>
> In that case, determining the attachment file name is non-trivial -- please consider a file name having multiple dots and a file name having no dots. As such, the process of determining the file name is put on the debug log if debug=1 URL parameter is supplied.

Added:

>
>

Command Line Scripts

Details on command line scripts located in the twiki/tools directory.

Added:

>
>

`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.

Line: 446 to 487

Example: geturl.pl some.domain /some/dir/file.html 80
Will get: http://some.domain:80/some/dir/file.html

Added:

>
>

`rewriteshebang.pl`

Simple script to rewrite the #!/usr/bin/perl shebang lines specific to your local Perl installation. It will rewrite the first line of all your TWiki cgi scripts so they use a different shebang line. Use it if your perl is in a non-standard location, or you want to use a different interpreter (such as 'speedy').

Added:

>
>

`tick_twiki.pl`

Added:

>
>

This script executes a number of non-essential regular administration tasks that will help keep your TWiki healthy and happy, such as removing expired sessions and lease files.

It is intended to be run as a cron job or a scheduled task once a week. Example crontab entry:

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 ARC TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiScripts.