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
<-- -->
Sorted ascending
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#mdrepo_script_from_command_line and MetadataRepository#mdrepo_script_from_browser.

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#VarSEARCH 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#WebStatistics_site_statistics 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.

ALERT! 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. http://denali.phys.uniroma1.it/twiki/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:

 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2019 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.