File Attachment Controls

Clicking on a Manage link takes you to a new page that looks a bit like this (depending on what skin is selected):

• The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.

• The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
  • To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
  • To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.

Known Issues

• Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
• Attachments are not secured. Anyone can read them if they know the name of the web, topic and attachment.

Back to top

TWiki Forms

Add structure to content with forms attached to twiki topics. TWiki forms (with form fields) and formatted search are the base for building database applications.

Overview

By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. A form is enabled for a web and can be added to a topic. The form data is shown in tabular format when the topic is viewed, and can be changed in edit mode using edit fields, radio buttons, check boxes and list boxes. Many different form types can be defined in a web, though a topic can only have one form attached to it at a time.

Typical steps to build an application based on TWiki forms:

1. Define a form template
2. Enable the form for a web
3. Add the form to a template topic
4. Build an HTML form to create new topics based on that template topic
5. Build a FormattedSearch to list topics that share the same form

Defining a Form

1. Create a new topic with your form name: YourForm, ExpenseReportForm, InfoCategoryForm, RecordReviewForm, whatever you need.
2. Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, Tooltip message, and Attributes (see sample below).
3. For each field, fill in a new line; for the type of field, select from the list.
4. Save the topic (you can later choose to enable/disable individual forms).

Example:
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| TopicClassification | select | 1 | NoDisclosure, PublicSupported, PublicFAQ | blah blah... |   |
| OperatingSystem | checkbox | 3 | OsHPUX, OsLinux, OsSolaris, OsWin | blah blah... |   |
| OsVersion | text | 16 | | blah blah... |   |

Name	Type	Size	Values	Tooltip message	Attributes
TopicClassification	select	1	NoDisclosure, PublicSupported, PublicFAQ	blah blah...
OperatingSystem	checkbox	3	OsHPUX, OsLinux, OsSolaris, OsWin	blah blah...
OsVersion	text	16		blah blah...

See structure of a form for full details of what types are available and what all the columns mean.

You can also retrieve possible values for select, checkbox or radio types from other topics:

Example:

• In the WebForm topic, define the form:
  

  Name	Type	Size	Values	Tooltip message	Attributes
  TopicClassification	select	1		blah blah...
  OperatingSystem	checkbox	3		blah blah...
  OsVersion	text	16		blah blah...

  
  Leave the Values field blank.

• Then in the TopicClassification topic, define the possible values:
  | *Name*            |
| NoDisclosure      |
| Public Supported  |
| Public FAQ        |
  

  Name
  NoDisclosure
  Public Supported
  Public FAQ

Field values can also be set using the result of expanding other TWiki variables. For example,

%SEARCH{"Office$" scope="topic" web="%USERSWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%

When used in the value field of the form definition, this will find all topic names in the Main web which end in "Office" and use them as the legal field values.

Enabling Forms by Web

Forms have to be enabled for each individual web. The WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates.

Example:

• Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm

• With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.
• You have to list the available form topics explicitly. You cannot use a SEARCH to define WEBFORMS.

Adding a form to a topic

• Edit the topic and follow the "Add form" button to add a Form. This is typically done to a template topic, either to the WebTopicEditTemplate topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.

• Additionally a new topic can be given a Form using the formtemplate parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values:
  • other than checkboxes: name, ex: ?BugPriority=1
  • checkbox: namevalue=1, ex: ?ColorRed=1.
    Boxes with a tick must be specified.
  • Example: This will add a textfield for the new topic name and a "Create"-Button to your topic. When the button is pressed, the topic editor will open with the form "MyForm" already attached to the new topic.

        <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/">
           <input type="hidden" name="formtemplate" value="MyForm" />
           New topic name <input type="text" name="topic" size="40" />
           <input type="submit" class="twikiSubmit" value="Create" />
        </form>
           

• Note: You can create a topic in one step, without going through the edit screen. To do that, specify the save script instead of the edit script in the form action. When you specify the save script you have to use the "post" method. Example:

      <form name="newtopic" action="%SCRIPTURLPATH{"save"}%/%WEB%/" method="post">
         .....
      </form>
         

• The edit and save scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.

• Tip: For TWiki applications you can automatically generate unique topicnames.

• Note: Initial values will not be set in the form of a new topic if you only use the formtemplate parameter.

Changing a form

• You can change a form definition, and TWiki will try to make sure you don't lose any data from the topics that use that form.

• If you change the form definition, the changes will not take affect in a topic that uses that form until you edit and save it.

• If you add a new field to the form, then it will appear next time you edit a topic that uses the form.

• If you delete a field from the form, or change a field name, then the data will not be visible when you edit the topic (the changed form definition will be used). If you save the topic, the old data will be lost (though thanks to revision control, you can always see it in older versions of the topic)

• If two people edit the same topic containing a form at exactly the same time, and both change fields in the form, TWiki will try to merge the changes so that no data is lost.

Structure of a Form Template

A Form Template specifies the fields in a form. A Form Template is simply a page containing a TWiki table, where each row of the table specifies one form field.

Each column of the table is one element of an entry field: Name, Type, Size, Values, Tooltip message, and Attributes.

The Name, Type and Size columns are required. Other columns are optional. The form must have a header row (e.g. | *Name* | *Type* | *Size* |).

Name is the name of the form field.

The Type, Size and Value fields describe the legal values for this field, and how to display them.

• Type checkbox specifies one or more checkboxes. The Size field specifies how many checkboxes will be displayed on each line. The Value field should be a comma-separated list of item labels.
  • Type checkbox+buttons will add Set and Clear buttons to the basic checkbox type.
• Type radio is like checkbox except that radio buttons are mutually exclusive; only one can be selected.
• Type label specifies read-only label text. The Value field should contain the text of the label.
• Type select specifies a select box. The Value field should contain a comma-separated list of options for the box. The Size field can specify a fixed size for the box (e.g. 1, or a range e.g. 3..10. If you specify a range, then the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options.
  • There are two modifiers that can be applied to the select type:
    • select+multi turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
    • select+values allows the definition of values that are different to the displayed text. For example:

      | Field 9 | select+values | 5 | One, Two=2, Three=III, Four | Various values formats |

      shows OneTwoThreeFour but the values or options Two and Three are 2 and III respectively.
      You can combine these modifiers e.g. select+multi+values
• Type text specifies a one-line text field. Size specifies the text box width in number of characters. Value is the initial (default) content when a new topic is created with this form template.
• Type textarea specifies a multi-line text box. The Size field should specify columns x rows, e.g. 80x6; default size is 40x5. As for text, the Value field specifies the initial text
• Type date specifies a single-line text box and a button next to it; clicking on the button will bring up a calendar from which the user can select a date. The date can also be typed into the text box. Size specifies the text box width in characters. As for text, the Value field specifies the initial text

Tooltip message is a message that will be displayed when the cursor is hovered over the field in edit view.

Attributes specifies special attributes for the field. Multiple attributes can be entered, separated by spaces.

• An attribute H indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
• An attribute M indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops page. Mandatory fields are indicated by an asterisks next to the field name.

For example, a simple form just supporting entry of a name and a date would look as follows:

| *Name* | *Type* | *Size* |
| Name   | text   | 80     |
| Date   | date   | 30     |

• Field names have to be unique.
• A very few field names are reserved. If you try to use one of these names, TWiki will automatically append an underscore to the name when the form is used.
• You can space out the title of the field, and it will still find the topic e.g. Aeroplane Manufacturers is equivalent to AeroplaneManufacturers.
• If a label field has no name, it will not be shown when the form is viewed, only when it is edited.
• Field names can in theory include any text, but you should stick to alphanumeric characters. If you want to use a non-wikiname for a select, checkbox or radio field, and want to get the values from another topic, you can use [[...]] links. This notation can also be used when referencing another topic to obtain field values, but a name other than the topic name is required as the name of the field.
• Leading and trailing spaces are not significant.

• The field value will be used to initialize a field when a form is created, unless specific values are given by the topic template or query parameters. The first item in the list for a select or radio type is the default item. For label, text, and textarea fields the value may also contain commas. checkbox fields cannot be initialized through the form template.
• Leading and trailing spaces are not significant.
• Field values can also be generated through a FormattedSearch, which must yield a suitable table as the result.
• Variables in the initial values of a form definition get expanded when the form definition is loaded.
  • If you want to use a | character in the initial values field, you have to precede it with a backslash, thus: \|.
  • You can use <nop> to prevent TWiki variables from being expanded.
  • The FormatTokens can be used to prevent expansion of other characters.

• The topic definition is not read when a topic is viewed.
• Form definition topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists. Note that view access is required to be able to edit topics that use the form definition, though view access to the form definition is not required to view a topic where the form has been used.

Values in Other Topics

| *Name*                 | *Type* | *Size* |
| AeroplaneManufacturers | select |        |

The AeroplaneManufacturers topic must contain a table, where each row of the table describes a possible value. The table only requires one column, Name. Other columns may be present, but are ignored.

For example:

| *Name* |
| Routan |
| Focke-Wulf |
| De Havilland |

Notes:

• The Values column must be empty in the referring form definition.

Extending the range of form data types

• any type name starting with checkbox
• any type name with +multi anywhere in the name

Hints and Tips

Build an HTML form to create new Form-based topics

• New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form. Template topics has more.

Searching for Form Data

Example
TWiki users often want to have an overview of topics they contributed to. With the $formfield parameter it is easy to display the value of a classification field next to the topic link:

| *Topic* | *Classification* |
%SEARCH{"%USERSWEB%.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on"
format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%

Searching forms this way is obviously pretty inefficient, but it's easy to do. If you want better performance, take a look at some of the structured wiki extensions that support higher performance searching e.g. TWiki:Plugins.DBCachePlugin.

Gotcha!

• Some browsers may strip linefeeds from text fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea.

Back to top

TWiki Templates

Definition of the templates used to render all HTML pages displayed in TWiki

Overview

Templates are plain text with embedded template directives that tell TWiki how to compose blocks of text together, to create something new.

There are two types of template:

• Master Templates: Define the HTML used to display TWiki pages.
• Template Topics: Define default text when you create a new topic

Tip: TWiki:TWiki.TWikiTemplatesSupplement on TWiki.org has supplemental documentation on TWiki templates.

Master Templates

Master templates are also used in the definition of TWikiSkins.

Master templates are stored as text files with the extension .tmpl. They are usually HTML with embedded template directives. The directives are expanded when TWiki wants to generate a user interface screen.

How Template Directives Work

• Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
• Directives:
  • %TMPL:INCLUDE{"file"}%: Includes a template file. The file is found as described below.
  • %TMPL:DEF{"block"}%: Define a block. All text between this and the next %TMPL:END% directive is removed and saved for later use with %TMPL:P.
  • %TMPL:END%: Ends a block definition.
  • %TMPL:P{"var"}%: Includes a previously defined block.
  • %{...}%: is a comment.
• Two-pass processing lets you use a variable before or after declaring it.
• Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the twiki.tmpl master template, like twiki.print.tmpl, that redefines the header and footer.
• Use of template directives is optional: templates work without them.
• NOTE: Template directives work only for templates: they do not get processed in normal topic text.

TMPL:P also supports simple parameters. For example, given the definition %TMPL:DEF{"x"}% x%P%z%TMPL:END% then %TMPL:P{"x" P="y"}% will expand to xyz.

Note that parameters can simply be ignored; for example, %TMPL:P{"x"}% will expand to x%P%z.

Any alphanumeric characters can be used in parameter names. You are highly recommended to use parameter names that cannot be confused with TWikiVariables.

Note that three parameter names, context, then and else are reserved. They are used to support a limited form of "if" condition that you can use to select which of two templates to use, based on a context identifier:

%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END%
%TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END%
%TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%

Finding Templates

The master templates shipped with a twiki release are stored in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the default template file for the twiki/bin/view script.

You can save templates in other directories as long as they are listed in the {TemplatePath} configuration setting. The {TemplatePath} is defined in the Miscellaneous section of the configure page.

You can also save templates in user topics (IF there is no possible template match in the templates directory). The {TemplatePath} configuration setting defines which topics will be accepted as templates.

Templates that are included with an explicit '.tmpl' extension are looked for only in the templates/ directory. For instance %TMPL:INCLUDE{"example.tmpl"}% will only return templates/example.tmpl, regardless of {TemplatePath} and SKIN settings.

The out-of-the-box setting of {TemplatePath} supports the following search order to determine which template file or topic to use for a particular script or %TMPL:INCLUDE{"script"}% statement. The skin path is set as described in TWikiSkins.

1. templates/web/script.skin.tmpl for each skin on the skin path
   • this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
2. templates/script.skin.tmpl for each skin on the skin path
3. templates/web/script.tmpl
   • this usage is supported for compatibility only and is deprecated. Store web-specific templates in TWiki topics instead.
4. templates/script.tmpl
5. The TWiki topic aweb.atopic if the template name can be parsed into aweb.atopic
6. The TWiki topic web.SkinSkinScriptTemplate for each skin on the skin path
7. The TWiki topic web.ScriptTemplate
8. The TWiki topic %SYSTEMWEB%.SkinSkinScriptTemplate for each skin on the skin path
9. The TWiki topic %SYSTEMWEB%.ScriptTemplate

• script refers to the script name, e.g view, edit
• Script refers to the same, but with the first character capitalized, e.g View
• skin refers to a skin name, e.g dragon, pattern. All skins are checked at each stage, in the order they appear in the skin path.
• Skin refers to the same, but with the first character capitalized, e.g Dragon
• web refers to the current web

For example, the example template file will be searched for in the following places, when the current web is Thisweb and the skin path is print,pattern:

1. templates/Thisweb/example.print.tmpl deprecated; don't rely on it
2. templates/Thisweb/example.pattern.tmpl deprecated; don't rely on it
3. templates/example.print.tmpl
4. templates/example.pattern.tmpl
5. templates/Thisweb/example.tmpl deprecated; don't rely on it
6. templates/example.tmpl
7. Thisweb.PrintSkinExampleTemplate
8. Thisweb.PatternSkinExampleTemplate
9. Thisweb.ExampleTemplate
10. TWiki.PrintSkinExampleTemplate
11. TWiki.PatternSkinExampleTemplate
12. TWiki.ExampleTemplate

Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the view and edit scripts, for example when a topic-specific template is required. Two preference variables can be used to override the templates used:

• VIEW_TEMPLATE sets the template to be used for viewing a topic
• EDIT_TEMPLATE sets the template for editing a topic.

TMPL:INCLUDE recursion for piecewise customisation, or mixing in new features

If there is recursion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains %TMPL:INCLUDE{"twiki"}%, the templating system will include the next twiki.SKIN in the skin path. For example, to create a customisation of pattern skin, where you only want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%

The default {TemplatePath} will not give you the desired result if you put these statements in the topic Thisweb.YourlocalSkinViewTemplate. The default {TemplatePath} will resolve the request to the template/view.pattern.tmpl, before it gets to the Thisweb.YourlocalSkinViewTemplate resolution. You can make it work by prefixing the {TemplatePath} with: $web.YourlocalSkin$nameTemplate.

Default master template

twiki.tmpl is the default master template. It defines the following sections.

Template Topics

The second type of template in TWiki are template topics. Template topics define the default text for new topics. There are four types of template topic:

When you create a new topic using the edit script, TWiki locates a topic to use as a content template according to the following search order:

1. A topic name specified by the templatetopic CGI parameter
   • if no web is specified, the current web is searched first and then the TWiki web
2. WebTopicEditTemplate in the current web
3. WebTopicEditTemplate in the TWiki web

Variable Expansion

TWikiVariables located in template topics get expanded as follows when a new topic is created.

1. Default variable expansion

The following variables used in a template topic automatically get expanded when new topic is created based on it:

2. Preventing variable expansion

In a template topic, embed text that you do not want expanded inside a %STARTSECTION{type="templateonly"}% ... %ENDSECTION{type="templateonly"}% section. For example, you might want to write this in the template topic:

%STARTSECTION{type="templateonly"}%
This template can only be changed by:
   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
%ENDSECTION{type="templateonly"}%

%NOP% can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation. For example, escape %SERVERTIME% with %SER%NOP%VERTIME%.

3. Control over variable expansion

You can forcefully expand TWikiVariables by placing them inside a type="expandvariables" section in the template topic, such as:

 ...  

Example:

If you have the following content in a template topic:

   * %TWIKIWEB%.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners
   * %TWIKIWEB%.WelcomeGuest - starting points on TWiki
   * %TWIKIWEB%.TWikiUsersGuide - complete TWiki documentation
   * Sandbox.%HOMETOPIC% - try out TWiki on your own
   * Sandbox.%TOPIC%Sandbox - just for me

you will get this raw text in new topics based on that template topic:

   * TWiki.ATasteOfTWiki - view a short introductory presentation on TWiki for beginners
   * TWiki.WelcomeGuest - starting points on TWiki
   * TWiki.TWikiUsersGuide - complete TWiki documentation
   * Sandbox.WebHome - try out TWiki on your own
   * Sandbox.JimmyNeutronSandbox - just for me

Specifying a Form

When you create a new topic based on a template, you often want the new topic to have a form attached to it. You can attach a form to the template topic, in which case it will be copied into the new topic.

Sometimes this isn't quite what you want, as it copies all the existing data from the template topic into the new topic. To avoid this and use the default values specified in the form definition instead, you can use the formtemplate CGI parameter to the edit script to specify the name of a form to attach.

See TWikiScripts for information about all the other parameters to edit.

Automatically Generated Topic Names

For TWiki applications it is useful to be able to automatically generate unique topicnames, such as BugID0001, BugID0002, etc. You can add AUTOINC<n> to the topic name in the edit and save scripts, and it will be replaced with an auto-incremented number on topic save. <n> is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.

Examples:

• BugAUTOINC0 - creates topic names Bug0, Bug1, Bug2, ... (does not sort properly)
• ItemAUTOINC0000 - creates topic names Item0000, Item0001, Item0002, ... (sorts properly up to 9999)
• DocIDAUTOINC10001 - start with DocID10001, DocID10002, ... (sorts properly up to 99999; auto-links)

Example link to create a new topic:

[[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]

Template Topics in Action

Here is an example for creating new topics (in the Sandbox web) based on a specific template topic and form:

The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:

<form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/">
   * New example topic: 
     <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" />
     <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
     <input type="hidden" name="topicparent" value="%TOPIC%" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="hidden" name="onlynewtopic" value="on" />
     <input type="submit" class="twikiSubmit" value="Create" />
</form>

Note: You can create a topic in one step, without going through the edit screen. To do that, specify the save script instead of the edit script in the form action. When you specify the save script you have to use the "post" method. Example:

<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post">
    ...
</form>

The edit and save scripts understand many more parameters, see TWikiScripts#edit and TWikiScripts#save for details.

TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is:
-- %WIKIUSERNAME% - %DATE%

Using Absolute vs Relative URLs in Templates

When you use TWikiVariables such as %PUBURL% and %PUBURLPATH% in templates you should be aware that using %PUBURL% instead of %PUBURLPATH% puts absolute URLs in the produced HTML. This means that when a user saves a TWiki page in HTML and emails the file to someone outside a company firewall, the receiver has a severe problem viewing it. It is therefore recommended always to use the %PUBURLPATH% to refer to images, CSS, Javascript files etc so links become relative. This way browsers just give up right away and show a usable html file.

Related Topics: TWikiSkins, TWikiForms, TWikiScripts, DeveloperDocumentationCategory, AdminDocumentationCategory

Back to top

TWiki Skins

Skins overlay regular templates to give different looks and feels to TWiki screens.

Overview

TWiki uses TWikiTemplates files as the basis of all the screens it uses to interact with users. Each screen has an associated template file that contains the basic layout of the screen. This is then filled in by the code to generate what you see in the browser.

TWiki ships with a default set of template files that give a very basic, CSS-themable, look-and-feel. TWiki also includes support for skins that can be selected to give different, more sophisticated, look and feels. A default TWiki installation will usually start up with the PatternSkin already selected. Skins may also be defined by third parties and loaded into a TWiki installation to give more options. To see how TWiki looks when no skin is selected, view this topic with a non-existant skin.

Topic text is not affected by the choice of skin, though a skin can be defined to use a CSS (Cascading Style Sheet), which can sometimes give a radically different appearance to the text.

Relevant links on TWiki.org:

• TWiki:TWiki.TWikiSkinsSupplement - tip: supplemental documentation on TWiki skins
• TWiki:Plugins.SkinPackage - list of all contributed skin packages
• TWiki:Plugins.SkinDevelopment - discussion and feedback on contributed skins
• TWiki:Plugins.SkinBrainstorming - open forum for new skin ideas
• TWiki:Plugins.SkinPackageHowTo - template to create a new skin package

See other types of extensions: TWikiAddOns, TWikiContribs, TWikiPlugins

Changing the default TWiki skin

TWiki default ships with the skin PatternSkin activated. You can set the skin for the whole site, a single web or topic, or for each user individually, by setting the SKIN variable to the name of a skin. If the skin you select doesn't exist, then TWiki will pick up the default templates.

Defining Skins

You may want to define your own skin, for example to comply with corporate web guidelines, or because you have a aesthetic vision that you want to share. There are a couple of places you an start doing this.

The TWikiTemplates files used for skins are located in the twiki/templates directory and are named according to the skin: <scriptname>.<skin>.tmpl. Skin files may also be defined in TWiki topics - see TWikiTemplates for details.

To start creating a new skin, copy the default TWikiTemplates (like view.tmpl), or copy an existing skin to use as a base for your own skin. You should only need to copy the files you intend to customise, as TWiki can be configured to fall back to another skin if a template is not defined in your skin. Name the files as described above (for example view.myskin.tmpl.

If you use PatternSkin as your starting point, and you want to modify the layout, colors or even the templates to suit your own needs, have a look first at the topics PatternSkinCustomization and PatternSkinCssCookbook.

For your own TWiki skin you are encouraged to show a small 80x31 pixel logo at the bottom of your skin:

<a href="http://twiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif" alt="This site is powered by the TWiki collaboration platform" width="80" height="15" title="This site is powered by the TWiki collaboration platform" border="0" /></a>

The standard TWiki skins show the logo in the %WEBCOPYRIGHT% variable.

Note: Two skin names have reserved meanings; text skin, and skin names starting with rss have hard-coded meanings.

The following template files are used for TWiki screens, and are referenced in the TWiki core code. If a skin doesn't define its own version of a template file, then TWiki will fall back to the next skin in the skin path, or finally, to the default version of the template file.

(Certain template files are expected to provide certain TMPL:DEFs - these are listed in sub-bullets)

• addform - used to select a new form for a topic
• attachagain - used when refreshing an existing attachment
• attachnew - used when attaching a new file to a topic
• attachtables - defines the format of attachments at the bottom of the standard topic view
  • ATTACH:files:footer, ATTACH:files:header, ATTACH:files:row, ATTACH:versions:footer, ATTACH:versions:header, ATTACH:versions:row
• changeform - used to change the form in a topic
• changes - used by the changes script
• edit - used for the edit screen
• form
• formtables - used to defined the format of forms
  • FORM:display:footer, FORM:display:header, FORM:display:row
• login - used for loggin in when using the TemplateLoginManager
  • LOG_IN, LOG_IN_BANNER, LOG_OUT, LOGGED_IN_BANNER, NEW_USER_NOTE, UNRECOGNISED_USER
• moveattachment - used when moving an attachment
• oopsaccessdenied - used to format Access Denied messages
  • no_such_topic, no_such_web, only_group, topic_access
• oopsattention - used to format Attention messages
  • already_exists, bad_email, bad_ver_code, bad_wikiname, base_web_missing, confirm, created_web, delete_err, invalid_web_color, invalid_web_name, in_a_group, mandatory_field, merge_notice, missing_action, missing_fields, move_err, missing_action, no_form_def, no_users_to_reset, notwikiuser, oversized_upload, password_changed, password_mismatch, problem_adding, remove_user_done, rename_err, rename_not_wikiword, rename_topic_exists, rename_web_err, rename_web_exists, rename_web_prerequisites, reset_bad, reset_ok, save_error, send_mail_error, thanks, topic_exists, unrecognized_action, upload_name_changed, web_creation_error, web_exists, web_missing, wrong_password, zero_size_upload
• oopschangelanguage - used to prompt for a new language when internationalisation is enabled
• oopsgeneric - a basic dialog for user information; provides "ok" button only
• oopslanguagechanged - used to confirm a new language when internationalisation is enabled
• oopsleaseconflict - used to format lease Conflict messages
  • lease_active, lease_old
• preview - used for previewing edited topics before saving
• rdiff - used for viewing topic differences
• registernotify - used by the user registration system
• registernotifyadmin - used by the user registration system
• rename - used when renaming a topic
• renameconfirm - used when renaming a topic
• renamedelete - used when renaming a topic
• renameweb - used when renaming a web
• renamewebconfirm - used when renaming a web
• renamewebdelete - used when renaming a web
• searchbookview - used to format inline search results in book view
• searchformat - used to format inline search results
• search - used by the search CGI script
• settings
• view - used by the view CGI script
• viewprint - used to create the printable view

twiki.tmpl is a master template conventionally used by other templates, but not used directly by code.

Note: Make sure templates do not end with a newline. Any newline will expand to an empty <p /> in the generated html. It will produce invalid html, and may break the page layout.

Partial customisation, or adding in new features to an existing skin

You can use recusion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains %TMPL:INCLUDE{"twiki"}%, the templating system will include the next twiki.SKIN in the skin path. For example, to create a customisation of pattern skin, where you only want to remove the edit & WYSIWYG buttons from view page, you create only a view.yourlocal.tmpl:

%TMPL:INCLUDE{"view"}%
%TMPL:DEF{"edit_topic_link"}%%TMPL:END%
%TMPL:DEF{"edit_wysiwyg_link"}%%TMPL:END%

Because ClassicSkin and the default templates use the same Template definition names, you can over-ride the edit links in them (or any skin derived from them) using the same view.yourlocal.tmpl (just set SKIN=yourlocal,classic either in TWikiPreferences for globally, or a Web's Webname.WebPreferences for a particular web)

Variables in Skins

You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:

The "Go" Box and Navigation Box

The default skins include a "Go" box, also called "Jump" box, to jump to a topic.

The box also understands URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onchange method of the select tag to fill the selected URL into the "Go" box field, then submits the form.

Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:

Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous, {AllowRedirectUrl}).

Using Cascading Style Sheets

CSS files are gererally attachments to the skin topic that are included in the the skin templates - in the case of PatternSkin in the template styles.pattern.tmpl.

• To see how CSS is used in the default TWiki skin, see: PatternSkin
• If you write a complete new skin, this is the syntax to use in a template file:

<style type='text/css' media='all'>@import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');</style>

Attachment Tables

The format of standard attachment tables is defined through the use of special TWiki template macros which by default, are defined in the attachtables.tmpl template using the %TMPL:DEF macro syntax described in TWikiTemplates. These macros are:

The format of tables of file versions in the Upload screen can also be changed, using the macros:

The ATTACH:row macros are expanded for each file in the attachment table, using the following special tags:

Packaging and Publishing Skins

See TWiki:Plugins/SkinPackagingHowTo and TWiki:Plugins/SkinDeveloperFAQ

Browsing Installed Skins

You can try out all installed skins in the TWikiSkinBrowser.

Activating Skins

TWiki uses a skin search path, which lets you combine skins additively. The skin path is defined using a combination of TWikiVariables and URL parameters.

TWiki works by asking for a template for a particular function - for example, 'view'. The detail of how templates are searched for is described in TWikiTemplates, but in summary, the templates directory is searched for a file called view.skin.tmpl, where skin is the name of the skin e.g. pattern. If no template is found, then the fallback is to use view.tmpl. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern then view.local.tmpl will be searched for first, then view.pattern.tmpl and finally view.tmpl.

The basic skin is defined by a SKIN setting:

• Set SKIN = catskin, bearskin

You can also add a parameter to the URL, such as ?skin=catskin,bearskin:

• https://wiki.planta.de/twiki/bin/view/TWiki_/TWikiSkins?skin=catskin,bearskin

Setting SKIN (or the ?skin parameter in the URL) replaces the existing skin path setting, for the current page only. You can also extend the existing skin path as well, using covers.

• Set COVER = ruskin

This pushes a different skin to the front of the skin search path (so for our example above, that final skin path will be ruskin, catskin, bearskin). There is also an equivalent cover URL parameter. The difference between setting SKIN vs. COVER is that if the chosen template is not found (e.g., for included templates), SKIN will fall back onto the next skin in line, or the default skin, if only one skin was present, while COVER will always fall back onto the current skin.

An example would be invoking the printable mode, which is achieved by applying ?cover=print. The view.print.tmpl simply invokes the viewprint template for the current skin which then can appropriately include all other used templates for the current skin. Where the printable mode be applied by using SKIN, all skins would have the same printable appearance.

The full skin path is built up as follows: SKIN setting (or ?skin if it is set), then COVER setting is added, then ?cover.

Hard-Coded Skins

The text skin is reserved for TWiki internal use.

Skin names starting with rss also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type header will be forced to text/xml.

Related Topics: TWikiSkinBrowser, AdminDocumentationCategory, DeveloperDocumentationCategory, TWiki:TWiki.TWikiSkinsSupplement

-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.CrawfordCurrie

Back to top

TWiki Meta Data

Additional topic data, program-generated or from TWikiForms, is stored embedded in the topic text using META: tags

Overview

By default, TWiki stores topics in files on disk, in a really simple and obvious directory structure. The big advantage of this approach is that it makes it really easy to manipulate topics from outside TWiki, and is also very safe; there are no complex binary indexes to maintain, and moving a topic from one TWiki to another is as simple as copying a couple of text files.

To keep eveything together in one place, TWiki uses a simple method for embedding additional data (program-generated or from TWikiForms) in topics. It does this using META: tags.

META: data includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info.

Meta Data Syntax

• Format is the same as in TWikiVariables, except all fields have a key.
  • %META:<type>{key1="value1" key2="value2" ...}%

• Order of fields within the meta variables is not defined, except that if there is a field with key name, this appears first for easier searching (note the order of the variables themselves is defined).

• Each meta variable is on one line.

• Values in meta-data are URL encoded so that characters such as \n can be stored.

Example of Format

%META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}%
   text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
   by="TopicMoverWikiName" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%

Meta Data Specifications

The current version of Meta Data is 1.0, with support for the following variables.

META:TOPICINFO

META:TOPICMOVED

This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.

%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%

Notes:

• at present version number is not supported directly, it can be inferred from the RCS history.
• there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.

META:TOPICPARENT

META:FILEATTACHMENT

Extra fields that are added if an attachment is moved:

META:FORM

META:FIELD

Should only be present if there is a META:FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.

Recommended Sequence

There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:

• form fields remain in the order they are defined
• the diff function output appears in a logical order

The recommended sequence is:

• META:TOPICINFO
• META:TOPICPARENT (optional)
• text of topic
• META:TOPICMOVED (optional)
• META:FILEATTACHMENT (0 or more entries)
• META:FORM (optional)
• META:FIELD (0 or more entries; FORM required)

Viewing Meta Data in Page Source

When viewing a topic the Raw Text link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic

Rendering Meta Data

Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.

You can render form fields in topic text by using the FORMFIELD variable. Example:
%FORMFIELD{"TopicClassification"}%
For details, see VarFORMFIELD.

Current support covers:

Note: SEARCH can also be used to render meta data, see examples in FormattedSearch and SearchPatternCookbook.

Related Topics: DeveloperDocumentationCategory, UserDocumentationCategory

Back to top

TWiki Add-Ons

Add functionality to TWiki with extensions not based on the TWiki scripts.

Overview

An add-on runs separately from the TWiki scripts, e.g. for data import, export to static HTML, etc. Add-Ons normally do not call any TWiki code directly, though may invoke TWiki scripts. There are different types of add-ons, they may be stand alone scripts, browser plugins, office tool extensions, or even a set of TWiki topics that form a TWiki application.

Relevant links on TWiki.org:

• TWiki:Plugins.AddOnPackage - list of all contributed add-on scripts
• TWiki:Plugins.AddOnDevelopment - discussion and feedback on contributed add-on scripts
• TWiki:Plugins.AddOnBrainstorming - open forum for new add-on script ideas
• TWiki:Plugins.AddOnPackageHowTo - instructions and template to create a new add-on topic

See other types of extensions: TWikiContribs, TWikiPlugins, TWikiSkins

Add-Ons Installed on this TWiki

• GenPDFAddOn: Generate a PDF from a single TWiki page - version 02 Jul 2008
  Author: TWiki:Main/BrianSpinar, TWiki:Main/WadeTurland - last modified: r3 - 2010-11-23 - 12:32 - AdminIstrator
• ScrollBoxAddOn: Add scroll boxes, image rotation and static boxes to TWiki pages - version 2013-10-11
  Author: TWiki:Main.PeterThoeny - last modified: r0 - 2013-10-11 - 18:47 - TWikiContributor

Installing Add-Ons

• Download an add-on from TWiki:Plugins.AddOnPackage.
• Follow the installation instructions in the add-on topic.

Creating new Add-Ons

• Visit TWiki:Plugins.AddOnPackageHowTo and follow the instructions.

Back to top

TWiki Contribs

Reusable code that may be used over several plugins and add-ons.

Overview

TWiki contribs extend the functionality of TWiki, typically used by plugins and add-ons. They may also provide alternative implementations for sections of the TWiki core e.g. user management, or when an extension just can't be implemented as a plugin because it requires very close access to TWiki internals.

Relevant links on TWiki.org:

• TWiki:Plugins.ContribPackage - list of all contributed contrib packages
• TWiki:Plugins.ContribDevelopment - discussion and feedback on contributed packages
• TWiki:Plugins.ContribBrainstorming - open forum for new contrib ideas
• TWiki:Plugins.ContribPackageHowTo - instructions and template to create a new contrib package

See other types of extensions: TWikiAddOns, TWikiPlugins, TWikiSkins

TWiki Contribs Installed on this TWiki

• BehaviourContrib: Behaviour Javascript event library to create javascript based interactions that degrade well when javascript is not available - version 15560 (12 Dec 2008)
  Author: TWiki:Main.ArthurClemens - last modified: r7 - 2009-08-04 - 13:35 - TWikiAdminUser
• JSCalendarContrib: Mishoo JSCalendar: A pop-up calendar for use in TWiki forms and TWiki applications - version 18048 (29 Apr 2009) of the Mishoo calendar
  Author: TWiki:Main/CrawfordCurrie http://c-dot.co.uk - last modified: r9 - 2009-04-28 - 03:33 - TWikiContributor
• MailerContrib: Supports e-mail notification of changes. - version 17629 (14 Oct 2008)
  Author: TWiki:Main/CrawfordCurrie (http://c-dot.co.uk) - last modified: r7 - 2008-12-06 - 09:02 - TWikiContributor
• TWikiUserMappingContrib: Traditional TWikiTopic based mapping and user management - version 4.2.1
  Author: - last modified: r2 - 2008-08-03 - 22:17 - TWikiContributor
• TipsContrib: Displays rotating list of "TWiki Tip-of-the-day" - version 2007-01-04
  Author: TWiki:Main.PeterThoeny, TWiki:Main.PaulineCheung - last modified: r6 - 2007-01-05 - 04:02 - TWikiContributor
• TwistyContrib: Twisty section javascript library to open/close content dynamically - version 20 Jun 2007 (version 1.4.1)
  Author: JavaScript written by TWiki:Main.ArthurClemens; Contrib packaged by TWiki:Main.RafaelAlvarez; original JavaScript written by TWiki:Main.SamHasler. - last modified: r9 - 2006-02-22 - 08:42 - TWikiContributor

Installing Contribs

• Download an add-on from TWiki:Plugins.ContribPackage.
• Follow the installation instructions in the contrib topic.

Creating new Contribs

• Visit TWiki:Plugins.ContribPackageHowTo and follow the instructions.

Back to top

TWiki Plugins

Add functionality to TWiki with readily available plugins; create plugins based on APIs

Overview

You can add plugins to extend TWiki functionality, without altering the core code. A plug-in approach lets you:

• add virtually unlimited features while keeping the main TWiki code compact and efficient;
• heavily customize an installation and still do clean updates to new versions of TWiki;
• rapidly develop new TWiki functions in Perl using the plugin API.

Everything to do with TWiki plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.

TWiki plugins are developed and contributed by interested members of the community. Plugins are provided on an 'as is' basis; they are not a part of TWiki, but are independently developed and maintained.

Relevant links on TWiki.org:

• TWiki:TWiki.TWikiPluginsSupplement - tip: supplemental documentation on TWiki plugins
• TWiki:Plugins.PluginPackage - list of all contributed plugin packages
• TWiki:Plugins.PluginDevelopment - discussion and feedback on contributed plugins
• TWiki:Plugins.PluginBrainstorming - open forum for new plugin ideas
• TWiki:Plugins.PluginPackageHowTo - template to create a new plugin package

See other types of extensions: TWikiAddOns, TWikiContribs, TWikiSkins

Installing Plugins

Each TWiki plugin comes with its own documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing. Many plugins have an install script that automates these steps for you.

Special Requirements: Some plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, and templates. You should be able to find detailed instructions in the plugin's documentation.

Each plugin has a standard release topic, located in the TWiki:Plugins web at TWiki.org. There's usually a number of other related topics, such as a developers page, and an appraisal page.

On-Site Pretesting

The recommended approach to testing new plugins before making them public is to create a second local TWiki installation, and test the plugin there. You can allow selected users access to the test area. Once you are satisfied that it won't compromise your main installation, you can install it there as well.

InstalledPlugins shows which plugins are: 1) installed, 2) loading properly, and 3) what TWiki:Codev.PluginHandlers they invoke. Any failures are shown in the Errors section. The %FAILEDPLUGINS% variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.

Some Notes on Plugin Performance

The performance of the system depends to some extent on the number of plugins installed and on the plugin implementation. Some plugins impose no measurable performance decrease, some do. For example, a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod_perl). You can only really tell the performance impact by installing the plugin and by measuring the performance with and without the new plugin. Use the TWiki:Plugins.PluginBenchmarkAddOn, or test manually with the Apache ab utility. Example on Unix:
time wget -qO /dev/null https://wiki.planta.de/twiki/bin/view/TWiki/AbcPlugin

If you need to install an "expensive" plugin, but you only need its functionality only in a subset of your data, you can disable it elsewhere by defining the %DISABLEDPLUGINS% TWiki variable.

Define DISABLEDPLUGINS to be a comma-separated list of names of plugins to disable. Define it in Main.TWikiPreferences to disable those plugins everywhere, in the WebPreferences topic to disable them in an individual web, or in a topic to disable them in that topic. For example,

   * Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin

Managing Installed Plugins

Some plugins require additional settings or offer extra options that you have to select. Also, you may want to make a plugin available only in certain webs, or temporarily disable it. And may want to list all available plugins in certain topics. You can handle all of these management tasks with simple procedures:

Enabling Plugins

Plugins can be enabled and disabled with the configure script. An installed plugin needs to be enabled before it can be used.

Plugin Evaluation Order

By default, TWiki executes plugins in alphabetical order on plugin name. It is possible to change the order, for example to evaluate database variables before the spreadsheet CALCs. This can be done with {PluginsOrder} in the plugins section of configure.

Plugin-Specific Settings

Some plugins are configured with plugin preferences variables, newer plugins with configure variables.

Configure variables are accessible though the configure interface.

Plugin preferences variables are defined in the plugin topic and can be overloaded. The SHORTDESCRIPTION preferences variable is always present, it is needed for the TWiki:Plugins repository on twiki.org. Example preferences variable defined in the TablePlugin topic:

• Set SHORTDESCRIPTION = Control attributes of tables and sorting of table columns

Preferences variables of active plugins can be retrieved anywhere in TWiki with %<pluginname>_<var>%, such as %TABLEPLUGIN_SHORTDESCRIPTION%. They can also be redefined with the %<pluginname>_<var>% setting at a lower level in the Main.TWikiPreferences or at the web level. For an easier upgrade it is recommended to customize plugin preferences variables in Main.TWikiPreferences only.

Listing Active Plugins

Plugin status variables let you list all active plugins wherever needed.

This site is running TWiki version TWiki-6.1.0, Mon, 16 Jul 2018, build 30610, plugin API version 6.10

%ACTIVATEDPLUGINS%

%PLUGINDESCRIPTIONS%

• SpreadSheetPlugin (2018-07-05, $Rev: 30478 (2018-07-16) $): Add spreadsheet calculation like "$SUM( $ABOVE() )" to TWiki tables and other topic text
• BackupRestorePlugin (2018-07-10, $Rev: 30551 (2018-07-16) $): Administrator utility to backup, restore and upgrade a TWiki site
• BeautifierPlugin (2012-12-02, $Rev: 24286 (2012-12-02) $): Highlights and formats code fragments
• ColorPickerPlugin (2018-07-05, $Rev: 30442 (2018-07-16) $): Color picker, packaged for use in TWiki forms and TWiki applications
• CommentPlugin (2018-07-05, $Rev: 30530 (2018-07-16) $): Quickly post comments to a page without an edit/preview/save cycle
• DatePickerPlugin (2018-07-05, $Rev: 30446 (2018-07-16) $): Pop-up calendar with date picker, for use in TWiki forms, HTML forms and TWiki plugins
• EditChapterPlugin (1.2, $Rev: 18557 (2010-04-30) $): An easy sectional edit facility
• EditTablePlugin (2018-07-05, $Rev: 30448 (2018-07-16) $): Edit TWiki tables using edit fields, date pickers and drop down boxes
• EmbedFlashPlugin (2011-01-11, $Rev: 20177 (2011-01-11) $): Embeds an Adobe Flash file
• HeadlinesPlugin (2018-07-13, $Rev: 30560 (2018-07-16) $): Show headline news in TWiki pages based on RSS and ATOM news feeds from external sites
• InterwikiPlugin (2018-07-05, $Rev: 30454 (2018-07-16) $): Write ExternalSite:Page to link to a page on an external site based on aliases defined in a rules topic
• JQueryPlugin (2021-03-19, $Rev: 30940 (2021-03-22) $): jQuery JavaScript library for TWiki
• PreferencesPlugin (2018-07-05, $Rev: 30528 (2018-07-16) $): Allows editing of preferences using fields predefined in a form
• SetGetPlugin (2018-07-05, $Rev: 30472 (2018-07-16) $): Set and get variables and JSON objects in topics, optionally persistently across topic views
• SlideShowPlugin (2018-07-05, $Rev: 30474 (2018-07-16) $): Create web based presentations based on topics with headings.
• SmiliesPlugin (2018-07-05, $Rev: 30476 (2018-07-16) $): Render smilies as icons, like for  :-) or for  :eek:
• TWikiSheetPlugin (2018-07-15, $Rev: 30604 (2018-07-16) $): Add TWiki Sheet spreadsheet functionality to TWiki tables
• TablePlugin (2018-07-05, $Rev: 30480 (2018-07-16) $): Control attributes of tables and sorting of table columns
• TagMePlugin (2018-07-05, $Rev: 30482 (2018-07-16) $): Tag wiki content collectively or authoritatively to find content by keywords
• TreeBrowserPlugin (2014-01-02, $Rev: 28100 (2014-09-29) $): Renders a list as a collapsable/expandable tree.
• TreePlugin (2015-08-12, $Rev: 29430 (2015-08-12) $): Dynamic generation of TWiki topic trees
• TwistyPlugin (2018-07-06, $Rev: 30497 (2018-07-16) $): Twisty section JavaScript library to open/close content dynamically
• WatchlistPlugin (2018-07-10, $Rev: 30536 (2018-07-16) $): Watch topics of interest and get notified of changes by e-mail
• WysiwygPlugin (2018-07-06, $Rev: 30528 (2018-07-16) $): Translator framework for WYSIWYG editors

%FAILEDPLUGINS%

The TWiki Plugin API

The Application Programming Interface (API) for TWiki plugins provides the specifications for hooking into the core TWiki code from your external Perl plugin module.

Available Core Functions

The TWikiFuncDotPm module (lib/TWiki/Func.pm) describes all the interfaces available to plugins. Plugins should only use the interfaces described in this module.

Note: If you use other core functions not described in Func.pm, you run the risk of creating security holes. Also, your plugin will likely break and require updating when you upgrade to a new version of TWiki.

Predefined Hooks

In addition to TWiki core functions, plugins can use predefined hooks, or callbacks, as described in the lib/TWiki/Plugins/EmptyPlugin.pm module.

• All but the initPlugin are disabled. To enable a callback, remove DISABLE_ from the function name.

TWiki:Codev/StepByStepRenderingOrder helps you decide which rendering handler to use.

Hints on Writing Fast Plugins

• Delay initialization as late as possible. For example, if your plugin is a simple syntax processor, you might delay loading extra Perl modules until you actually see the syntax in the text.
  • For example, use an eval block like this:
    eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
• Keep the main plugin package as small as possible; create other packages that are loaded if and only if they are used. For example, create sub-packages of BathPlugin in lib/TWiki/Plugins/BathPlugin/.
• Avoid using preferences in the plugin topic; set $NO_PREFS_IN_TOPIC if you possibly can, as that will stop TWiki from reading the plugin topic for every page. Use Config.spec instead.
• Use registered tag handlers
• Measure the performance to see the difference

Version Detection

To eliminate the incompatibility problems that are bound to arise from active open plugin development, a plugin versioning system is provided for automatic compatibility checking.

• All plugin packages require a $VERSION variable. This should be an integer, or a subversion version id.

• The initPlugin handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong.
  • The plugin initialization code does not register a plugin that returns 0 (or that has no initPlugin handler).

• $TWiki::Plugins::VERSION in the TWiki::Plugins module contains the TWiki plugin API version, currently 6.10.
  • You can also use the %PLUGINVERSION{}% variable to query the plugin API version or the version of installed plugins.

Security

• Badly written plugins can open huge security holes in TWiki. This is especially true if care isn't taken to prevent execution of arbitrary commands on the server.
• Don't allow sensitive configuration data to be edited by users. it is better to add sensitive configuration options to the %TWiki::cfg hash than adding it as preferences in the plugin topic.
  • Integrating with configure describes the steps
  • TWiki:Plugins.MailInContrib has an example
  • TWiki:Plugins.BuildContrib can help you with this
• Always use the TWiki::Sandbox to execute commands.
• Always audit the plugins you install, and make sure you are happy with the level of security provided. While every effort is made to monitor plugin authors activities, at the end of the day they are uncontrolled user contributions.

Creating Plugins

With a reasonable knowledge of the Perl scripting language, you can create new plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API provides the programming interface for TWiki.

Anatomy of a Plugin

A (very) basic TWiki plugin consists of two files:

• a Perl module, e.g. MyFirstPlugin.pm
• a documentation topic, e.g. MyFirstPlugin.txt

The Perl module can be a block of code that talks to with TWiki alone, or it can include other elements, like other Perl modules (including other plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call. In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.

The plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop plugins.

The TWiki:Plugins.BuildContrib module provides a lot of support for plugins development, including a plugin creator, automatic publishing support, and automatic installation script writer. If you plan on writing more than one plugin, you probably need it.

Creating the Perl Module

Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. The EmptyPlugin.pm module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.

If your plugin uses its own modules and objects, you must include the name of the plugin in the package name. For example, write Package MyFirstPlugin::Attrs; instead of just Package Attrs;. Then call it using:

use TWiki::Plugins::MyFirstPlugin::Attrs;
$var = MyFirstPlugin::Attrs->new();

Writing the Documentation Topic

The plugin documentation topic contains usage instructions and version details. It serves the plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package.) To create a documentation topic:

1. Copy the plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
   • enter the plugin name in the "How to Create a Plugin" section
   • click Create
   • select all in the Edit box & copy
   • Cancel the edit
   • go back to your site to the TWiki web
   • In the GoBox enter your plugin name, for example MyFirstPlugin, press enter and create the new topic
   • paste & save new plugin topic on your site
2. Customize your plugin topic.
   • Important: In case you plan to publish your plugin on TWiki.org, use Interwiki names for author names and links to TWiki.org topics, such as TWiki:Main/TWikiGuest. This is important because links should work properly in a plugin topic installed on any TWiki, not just on TWiki.org.
3. Document the performance data you gathered while measuring the performance
4. Save your topic, for use in packaging and publishing your plugin.

OUTLINE: Doc Topic Contents
Check the plugins web on TWiki.org for the latest plugin doc topic template. Here's a quick overview of what's covered:

Syntax Rules: <Describe any special text formatting that will be rendered.>"

Example: <Include an example of the plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>"

Plugin Settings: <Description and settings for custom plugin %VARIABLES%, and those required by TWiki.>"

• Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
  • Set <EXAMPLE = value added>

Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"

Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"

Packaging for Distribution

The TWiki:Plugins.BuildContrib is a powerful build environment that is used by the TWiki project to build TWiki itself, as well as many of the plugins. You don't have to use it, but it is highly recommended!

If you don't want (or can't) use the BuildContrib, then a minimum plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).

1. Distribute the plugin files in a directory structure that mirrors TWiki. If your plugin uses additional files, include them all:
   • lib/TWiki/Plugins/MyFirstPlugin.pm
   • data/TWiki/MyFirstPlugin.txt
   • pub/TWiki/MyFirstPlugin/uparrow.gif [a required graphic]
2. Create a zip archive with the plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
   • lib/TWiki/Plugins/MyFirstPlugin.pm
   • data/TWiki/MyFirstPlugin.txt
   • pub/TWiki/MyFirstPlugin/uparrow.gif

Measuring and Improving the Plugin Performance

A high quality plugin performs well. You can use the TWiki:Plugins.PluginBenchmarkAddOn to measure your TWiki:Plugins.PluginBenchmarks. The data is needed as part of the Documentation Topic.

See also Hints on Writing Fast Plugins.

Publishing for Public Use

You can release your tested, packaged plugin to the TWiki community through the TWiki:Plugins web. All plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins/PluginPackage.

Publish your plugin by following these steps:

1. Post the plugin documentation topic in the TWiki:Plugins/PluginPackage:
   • enter the plugin name in the "How to Create a Plugin" section, for example MyFirstPlugin
   • paste in the topic text from Writing the Documentation Topic and save
2. Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
3. Link from the doc page to a new, blank page named after the plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for plugins is handled in TWiki:Support.)
4. Put the plugin into the SVN repository, see TWiki:Plugins/ReadmeFirst (optional)

Once you have done the above steps once, you can use the BuildContrib to upload updates to your plugin.

Thank you very much for sharing your plugin with the TWiki community

Recommended Storage of Plugin Specific Data

Plugins sometimes need to store data. This can be plugin internal data such as cache data, or data generated for browser consumption such as images. Plugins should store data using TWikiFuncDotPm functions that support saving and loading of topics and attachments.

Plugin Internal Data

You can create a plugin "work area" using the TWiki::Func::getWorkArea() function, which gives you a persistent directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, TWiki::Func::storeFile() and TWiki::Func::readFile() are provided to persistently store and retrieve simple data in this area.

Web Accessible Data

Topic-specific data such as generated images can be stored in the topic's attachment area, which is web accessible. Use the TWiki::Func::saveAttachment() function to store the data.

Recommendation for file name:

• Prefix the filename with an underscore (the leading underscore avoids a name clash with files attached to the same topic)
• Identify where the attachment originated from, typically by including the plugin name in the file name
• Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
• Example: _GaugePlugin_img123.gif

Web specific data can be stored in the plugin's attachment area, which is web accessible. Use the TWiki::Func::saveAttachment() function to store the data.

Recommendation for file names in plugin attachment area:

• Prefix the filename with an underscore
• Include the name of the web in the filename
• Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
• Example: _Main_roundedge-ul.gif

Integrating with configure

Config.spec files are read during TWiki configuration. Once a Config.spec has defined a configuration item, it is available for edit through the standard configure interface. Config.spec files are stored in the 'plugin directory' e.g. lib/TWiki/Plugins/BathPlugin/Config.spec.

Structure of a Config.spec file

# ---+ BathPlugin
# This plugin senses the level of water in your bath, and ensures the plug
# is not removed while the water is still warm.

# **SELECT Plastic,Rubber,Metal**
# Select the plug type
$TWiki::cfg{BathPlugin}{PlugType} = 'Plastic';

# **NUMBER**
# Enter the chain length in cm
$TWiki::cfg{BathPlugin}{ChainLength} = '30';

# **BOOLEAN EXPERT**
# Turn this option off to disable the water temperature alarm
$TWiki::cfg{BathPlugin}{TempSensorEnabled} = '1';

if( $TWiki::cfg{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) {
    die "The bathwater is too hot for comfort";
}

The config.spec file is read by configure, and configure then writes LocalSite.cfg with the values chosen by the local site admin.

A range of types are available for use in Config.spec files:

All types can be followed by a comma-separated list of attributes.

See lib/TWiki.spec for many more examples.

Config.spec files are also used for other (non-plugin) extensions. in this case they are stored under the Contrib directory instead of the Plugins directory.

TWiki:TWiki/SpecifyingConfigurationItemsForExtensions has supplemental documentation on configure settings.

Maintaining Plugins

Discussions and Feedback on Plugins

Each published plugin has a plugin development topic on TWiki.org. Plugin development topics are named after your plugin and end in Dev, such as MyFirstPluginDev. The plugin development topic is a great resource to discuss feature enhancements and to get feedback from the TWiki community.

Maintaining Compatibility with Earlier TWiki Versions

The plugin interface (TWikiFuncDotPm functions and plugin handlers) evolve over time. TWiki introduces new API functions to address the needs of plugin authors. Plugins using unofficial TWiki internal functions may no longer work on a TWiki upgrade.

Organizations typically do not upgrade to the latest TWiki for many months. However, many administrators still would like to install the latest versions of a plugin on their older TWiki installation. This need is fulfilled if plugins are maintained in a compatible manner.

Tip: Plugins can be written to be compatible with older and newer TWiki releases. This can be done also for plugins using unofficial TWiki internal functions of an earlier release that no longer work on the latest TWiki codebase. Here is an example; the TWiki:TWiki.TWikiPluginsSupplement#MaintainPlugins has more details.

    if( $TWiki::Plugins::VERSION >= 1.1 ) {
        @webs = TWiki::Func::getListOfWebs( 'user,public' );
    } else {
        @webs = TWiki::Func::getPublicWebList( );
    }

Handling deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.

When a plugin defines deprecated handlers, a warning will be shown in the list generated by %FAILEDPLUGINS%. Admins who see these warnings should check TWiki.org and if necessary, contact the plugin author, for an updated version of the plugin.

Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %FAILEDPLUGINS%.

This is done by defining a map from the handler name to the TWiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with TWiki::Plugins versions before 1.1, we would add this to the plugin:

package TWiki::Plugins::SinkPlugin;
use vars qw( %TWikiCompatibility );
$TWikiCompatibility{endRenderingHandler} = 1.1;

Back to top

Official list of stable TWiki functions for Plugin developers

This module defines official functions that Plugins can use to interact with the TWiki engine and content.

Refer to EmptyPlugin and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.

Plugins should only use functions published in this module. If you use functions in other TWiki libraries you might create a security hole and you will probably need to change your Plugin when you upgrade TWiki.

Deprecated functions will still work in older code, though they should not be called in new Plugins and should be replaced in older Plugins as soon as possible.

The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 6.10. This can be shown by the %PLUGINVERSION% TWiki variable, and accessed in code using $TWiki::Plugins::VERSION. The 'Since' field in the function documentation refers to $TWiki::Plugins::VERSION.

Notes on use of $TWiki::Plugins::VERSION (from 1.2 forwards):

• If the major version (e.g. 1.) is the same then any plugin coded to use any earlier revision of the 1. API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to require plugins to be recoded.
• If the minor version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, deprecation of functions in the interface trigger a minor version increment. Note that deprecated functions are not removed, they are merely frozen, and plugin authors are recommended to stop using them.
• Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
• TWiki::Plugins::VERSION also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of TWiki::Plugins::VERSION it relates to.

Environment

getSkin( ) -> $skin

Get the skin path, set by the SKIN and COVER preferences variables or the skin and cover CGI parameters

Return: $skin Comma-separated list of skins, e.g. 'gnu,tartan'. Empty string if none.

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

getUrlHost( ) -> $host

Get protocol, domain and optional port of script URL

Return: $host URL host, e.g. "http://example.com:80"

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getScriptUrl( $web, $topic, $script, ... ) -> $url

Compose fully qualified URL

• $web - Web name, e.g. 'Main'
• $topic - Topic name, e.g. 'WebNotify'
• $script - Script name, e.g. 'view'
• ... - an arbitrary number of name=>value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2) will give .../view/x/y?a=1&b=2#XXX

Return: $url URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getViewUrl( $web, $topic ) -> $url

Compose fully qualified view URL

• $web - Web name, e.g. 'Main'. The current web is taken if empty
• $topic - Topic name, e.g. 'WebNotify'

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getPubUrlPath( ) -> $path

Get pub URL path

Return: $path URL path of pub directory, e.g. "/pub"

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

getExternalResource( $url ) -> $response

Get whatever is at the other end of a URL (using an HTTP GET request). Will only work for encrypted protocols such as https if the LWP CPAN module is installed.

Note that the $url may have an optional user and password, as specified by the relevant RFC. Any proxy set in configure is honoured.

The $response is an object that is known to implement the following subset of the methods of LWP::Response. It may in fact be an LWP::Response object, but it may also not be if LWP is not available, so callers may only assume the following subset of methods is available:

Note that if LWP is not available, this function:

1. can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are strongly recommended to require LWP.
2. Will not parse multipart content

In the event of the server returning an error, then is_error() will return true, code() will return a valid HTTP status code as specified in RFC 2616 and RFC 2518, and message() will return the message that was received from the server. In the event of a client-side error (e.g. an unparseable URL) then is_error() will return true and message() will return an explanatory message. code() will return 400 (BAD REQUEST).

Note: Callers can easily check the availability of other HTTP::Response methods as follows:

my $response = TWiki::Func::getExternalResource($url);
if (!$response->is_error() && $response->isa('HTTP::Response')) {
    ... other methods of HTTP::Response may be called
} else {
    ... only the methods listed above may be called
}

Since: TWiki::Plugins::VERSION 1.2

getCgiQuery( ) -> $query

Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set

Return: $query CGI query object; or 0 if script is called as a shell script

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getSessionKeys() -> @keys

Session keys are stored and retrieved using setSessionValue and getSessionValue.

Since: TWiki::Plugins::VERSION 1.2

getSessionValue( $key ) -> $value

Get a session value from the client session module

• $key - Session key

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 200)

setSessionValue( $key, $value ) -> $boolean

Set a session value.

• $key - Session key
• $value - Value associated with key

Since: TWiki::Plugins::VERSION 1.000 (17 Aug 2001)

clearSessionValue( $key ) -> $boolean

Clear a session value that was set using setSessionValue.

• $key - name of value stored in session to be cleared. Note that you cannot clear AUTHUSER.

Since: TWiki::Plugins::VERSION 1.1

getContext() -> \%hash

Get a hash of context identifiers representing the currently active context.

The context is a set of identifiers that are set during specific phases of TWiki processing. For example, each of the standard scripts in the 'bin' directory each has a context identifier - the view script has 'view', the edit script has 'edit' etc. So you can easily tell what 'type' of script your Plugin is being called within. The core context identifiers are listed in the IfStatements topic. Please be careful not to overwrite any of these identifiers!

Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in FirstPlugin .pm, you might write:

sub initPlugin {
   TWiki::Func::getContext()->{'MyID'} = 1;
   ...

sub initPlugin {
   if( TWiki::Func::getContext()->{'MyID'} ) {
      ...
   }
   ...

%TMPL:DEF{"ON"}% Not off %TMPL:END%
%TMPL:DEF{"OFF"}% Not on %TMPL:END%
%TMPL:P{context="MyID" then="ON" else="OFF"}%

%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%

Since: TWiki::Plugins::VERSION 1.1

pushTopicContext($web, $topic)

• $web - new web
• $topic - new topic

It is the duty of the caller to restore the original context by calling popTopicContext.

Note that this call does not re-initialise plugins, so if you have used global variables to remember the web and topic in initPlugin, then those values will be unchanged.

Since: TWiki::Plugins::VERSION 1.2

popTopicContext()

Returns the TWiki context to the state it was in before the pushTopicContext was called.

Since: TWiki::Plugins::VERSION 1.2

Preferences

getPreferencesValue( $key, $web ) -> $value

Get a preferences value from TWiki or from a Plugin

• $key - Preferences key
• $web - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

• Example for Plugin setting:
  • MyPlugin topic has: * Set COLOR = red
  • Use "MYPLUGIN_COLOR" for $key
  • my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );

• Example for preferences setting:
  • WebPreferences topic has: * Set WEBBGCOLOR = #FFFFC0
  • my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );

NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC is enabled in the plugin, then preferences set in the plugin topic will be ignored.

getPluginPreferencesValue( $key ) -> $value

Get a preferences value from your Plugin

• $key - Plugin Preferences key w/o PLUGINNAME_ prefix.

Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)

Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC is enabled in the plugin, then preferences set in the plugin topic will be ignored.

getPreferencesFlag( $key, $web ) -> $value

Get a preferences flag from TWiki or from a Plugin

• $key - Preferences key
• $web - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

• Example for Plugin setting:
  • MyPlugin topic has: * Set SHOWHELP = off
  • Use "MYPLUGIN_SHOWHELP" for $key
  • my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );

NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC is enabled in the plugin, then preferences set in the plugin topic will be ignored.

getPluginPreferencesFlag( $key ) -> $boolean

Get a preferences flag from your Plugin

• $key - Plugin Preferences key w/o PLUGINNAME_ prefix.

Note: This function will will only work when called from the Plugin.pm file itself. it will not work if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)

Since: TWiki::Plugins::VERSION 1.021 (27 Mar 2004)

NOTE: As of TWiki4.1, if $NO_PREFS_IN_TOPIC is enabled in the plugin, then preferences set in the plugin topic will be ignored.

setPreferencesValue($name, $val)

Set the preferences value so that future calls to getPreferencesValue will return this value, and %$name% will expand to the preference when used in future variable expansions.

The preference only persists for the rest of this request. Finalised preferences cannot be redefined using this function.

Returns 1 if the preference was defined, and 0 otherwise.

getWikiToolName( ) -> $name

Get toolname as defined in TWiki.cfg

Return: $name Name of tool, e.g. 'TWiki'

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

getMainWebname( ) -> $name

Get name of Main web as defined in TWiki.cfg

Return: $name Name, e.g. 'Main'

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

getTwikiWebname( ) -> $name

Get name of TWiki documentation web as defined in TWiki.cfg

Return: $name Name, e.g. 'TWiki'

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

User Handling and Access Control

getDefaultUserName( ) -> $loginName

Return: $loginName Default user name, e.g. 'guest'

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getCanonicalUserID( $user ) -> $cUID

• $user can be a login, wikiname or web.wikiname

If $user is undefined, it assumes the currently logged-in user.

Return: $cUID, an internal unique and portable escaped identifier for registered users. This may be autogenerated for an authenticated but unregistered user.

Since: TWiki::Plugins::VERSION 1.2

getWikiName( $user ) -> $wikiName

return the WikiName of the specified user if $user is undefined Get Wiki name of logged in user

• $user can be a cUID, login, wikiname or web.wikiname

Return: $wikiName Wiki Name, e.g. 'JohnDoe'

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getWikiUserName( $user ) -> $wikiName

return the userWeb.WikiName of the specified user if $user is undefined Get Wiki name of logged in user

• $user can be a cUID, login, wikiname or web.wikiname

Return: $wikiName Wiki Name, e.g. "Main.JohnDoe"

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

wikiToUserName( $id ) -> $loginName

• $id - Wiki name, e.g. 'Main.JohnDoe' or 'JohnDoe'. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.

Return: $loginName Login name of user, e.g. 'jdoe', or undef if not matched.

Note that it is possible for several login names to map to the same wikiname. This function will only return the first login name that maps to the wikiname.

returns undef if the WikiName is not found.

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

userToWikiName( $loginName, $dontAddWeb ) -> $wikiName

• $loginName - Login name, e.g. 'jdoe'. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.
• $dontAddWeb - Do not add web prefix if "1"

userToWikiName will always return a name. If the user does not exist in the mapping, the $loginName parameter is returned. (backward compatibility)

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames

• $email - email address to look up
• $dontAddWeb - Do not add web prefix if "1"

Since: TWiki::Plugins::VERSION 1.2

wikinameToEmails( $user ) -> @emails

• $user - wikiname of user to look up

Since TWiki 4.2.1, $user may also be a login name, or the name of a group.

Since: TWiki::Plugins::VERSION 1.2

isGuest( ) -> $boolean

Test if logged in user is a guest (TWikiGuest )

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

isAnAdmin( $id ) -> $boolean

Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.

• $id can be either a login name or a WikiName

Since: TWiki::Plugins::VERSION 1.2

isGroupMember( $group, $id ) -> $boolean

Find out if $id is in the named group. e.g.

if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
    ...
}

• $id can be a login name or a WikiName

Since: TWiki::Plugins::VERSION 1.2

eachUser() -> $iterator

Use it as follows:

    my $iterator = TWiki::Func::eachUser();
    while ($it->hasNext()) {
        my $user = $it->next();
        # $user is a wikiname
    }

WARNING on large sites, this could be a long list!

Since: TWiki::Plugins::VERSION 1.2

eachMembership($id) -> $iterator

• $id - WikiName or login name of the user. If $id is undef, defaults to the currently logged-in user.

Since: TWiki::Plugins::VERSION 1.2

eachGroup() -> $iterator

Use it as follows:

    my $iterator = TWiki::Func::eachGroup();
    while ($it->hasNext()) {
        my $group = $it->next();
        # $group is a group name e.g. TWikiAdminGroup
    }

WARNING on large sites, this could be a long list!

Since: TWiki::Plugins::VERSION 1.2

isGroup( $group ) -> $boolean

Checks if $group is the name of a group known to TWiki.

eachGroupMember($group) -> $iterator

Use it as follows:

    my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup');
    while ($it->hasNext()) {
        my $user = $it->next();
        # $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
    }

WARNING on large sites, this could be a long list!

Since: TWiki::Plugins::VERSION 1.2

checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -> $boolean

Check access permission for a topic based on the TWiki.TWikiAccessControl rules

• $type - Access type, required, e.g. 'VIEW', 'CHANGE'.
• $id - WikiName of remote user, required, e.g. "PeterThoeny". From TWiki 4.2.1, $id may also be a login name. If $id is '', 0 or undef then access is always permitted.
• $text - Topic text, optional. If 'perl false' (undef, 0 or ''), topic $web.$topic is consulted. $text may optionally contain embedded %META:PREFERENCE tags. Provide this parameter if:
  1. You are setting different access controls in the text to those defined in the stored topic,
  2. You already have the topic text in hand, and want to help TWiki avoid having to read it again,
  3. You are providing a $meta parameter.
• $topic - Topic name, required, e.g. 'PrivateStuff'
• $web - Web name, required, e.g. 'Sandbox'
• $meta - Meta-data object, as returned by readTopic. Optional. If undef, but $text is defined, then access controls will be parsed from $text. If defined, then metadata embedded in $text will be ignored. This parameter is always ignored if $text is undefined. Settings in $meta override Set settings in $text.

Note the weird parameter order is due to compatibility constraints with earlier TWiki releases.

Tip if you want, you can use this method to check your own access control types. For example, if you:

• Set ALLOWTOPICSPIN = IncyWincy

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

Webs, Topics and Attachments

getListOfWebs( $filter ) -> @webs

• $filter - spec of web types to recover

1. 'user' (for only user webs)
2. 'template' (for only template webs i.e. those starting with "_")

For example, the deprecated getPublicWebList function can be duplicated as follows:

   my @webs = TWiki::Func::getListOfWebs( "user,public" );

Since: TWiki::Plugins::VERSION 1.1

webExists( $web ) -> $boolean

Test if web exists

• $web - Web name, required, e.g. 'Sandbox'

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

createWeb( $newWeb, $baseWeb, $opts )

• $newWeb is the name of the new web.
• $baseWeb is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
• $opts is a ref to a hash that contains settings to be modified in

use Error qw( :try );
use TWiki::AccessControlException;

try {
    TWiki::Func::createWeb( "Newweb" );
} catch Error::Simple with {
    my $e = shift;
    # see documentation on Error::Simple
} catch TWiki::AccessControlException with {
    my $e = shift;
    # see documentation on TWiki::AccessControlException
} otherwise {
    ...
};

Since: TWiki::Plugins::VERSION 1.1

moveWeb( $oldName, $newName )

Move (rename) a web.

use Error qw( :try );
use TWiki::AccessControlException;

try {
    TWiki::Func::moveWeb( "Oldweb", "Newweb" );
} catch Error::Simple with {
    my $e = shift;
    # see documentation on Error::Simple
} catch TWiki::AccessControlException with {
    my $e = shift;
    # see documentation on TWiki::AccessControlException
} otherwise {
    ...
};

To delete a web, move it to a subweb of Trash

TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );

Since: TWiki::Plugins::VERSION 1.1

eachChangeSince($web, $time) -> $iterator

Get an iterator over the list of all the changes in the given web between $time and now. $time is a time in seconds since 1st Jan 1970, and is not guaranteed to return any changes that occurred before (now - {Store}{RememberChangesFor}). {Store}{RememberChangesFor}) is a setting in configure. Changes are returned in most-recent-first order.

Use it as follows:

    my $iterator = TWiki::Func::eachChangeSince(
        $web, time() - 7 * 24 * 60 * 60); # the last 7 days
    while ($iterator->hasNext()) {
        my $change = $iterator->next();
        # $change is a perl hash that contains the following fields:
        # topic => topic name
        # user => wikiname - wikiname of user who made the change
        # time => time of the change
        # revision => revision number *after* the change
        # more => more info about the change (e.g. 'minor')
    }

getTopicList( $web ) -> @topics

Get list of all topics in a web

• $web - Web name, required, e.g. 'Sandbox'

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

topicExists( $web, $topic ) -> $boolean

Test if topic exists

• $web - Web name, optional, e.g. 'Main'.
• $topic - Topic name, required, e.g. 'TokyoOffice', or "Main.TokyoOffice"

$web and $topic are parsed as described in the documentation for normalizeWebTopicName. Specifically, the Main is used if $web is not specified and $topic has no web specifier. To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.

Since: TWiki::Plugins::VERSION 1.000 (14 Jul 2001)

checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )

Check if a lease has been taken by some other user.

• $web Web name, e.g. "Main", or empty
• $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"

• $script The script to invoke when continuing with the edit

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

setTopicEditLock( $web, $topic, $lock )

• $web Web name, e.g. "Main", or empty
• $topic Topic name, e.g. "MyTopic", or "Main.MyTopic"
• $lock 1 to lease the topic, 0 to clear an existing lease

Takes out a "lease" on the topic. The lease doesn't prevent anyone from editing and changing the topic, but it does redirect them to a warning screen, so this provides some protection. The edit script always takes out a lease.

It is impossible to fully lock a topic. Concurrent changes will be merged.

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

saveTopic( $web, $topic, $meta, $text, $options ) -> $error

• $web - web for the topic
• $topic - topic name
• $meta - reference to TWiki::Meta object
• $text - text of the topic (without embedded meta-data!!!
• \%options - ref to hash of save options \%options may include:

  dontlog	don't log this change in twiki log
  forcenewrevision	force the save to increment the revision counter
  minor	True if this is a minor change, and is not to be notified

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

For example,

my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
$text =~ s/APPLE/ORANGE/g;
TWiki::Func::saveTopic( $web, $topic, $meta, $text, { forcenewrevision => 1 } );

Note: Plugins handlers ( e.g. beforeSaveHandler ) will be called as appropriate.

saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl

Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.

• $web - Web name, e.g. 'Main', or empty
• $topic - Topic name, e.g. 'MyTopic', or "Main.MyTopic"
• $text - Topic text to save, assumed to include meta data
• $ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK
• $dontNotify - Set to "1" if not to notify users of the change

This method is a lot less efficient and much more dangerous than saveTopic.

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

my $text = TWiki::Func::readTopicText( $web, $topic );

# check for oops URL in case of error:
if( $text =~ /^http.*?\/oops/ ) {
    TWiki::Func::redirectCgiQuery( $query, $text );
    return;
}
# do topic text manipulation like:
$text =~ s/old/new/g;
# do meta data manipulation like:
$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text

moveTopic( $web, $topic, $newWeb, $newTopic )

• $web source web - required
• $topic source topic - required
• $newWeb dest web
• $newTopic dest topic

The destination topic must not already exist.

Rename a topic to the $TWiki::cfg{TrashWebName} to delete it.

Since: TWiki::Plugins::VERSION 1.1

use Error qw( :try );

try {
    moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
} catch Error::Simple with {
    my $e = shift;
    # see documentation on Error::Simple
} catch TWiki::AccessControlException with {
    my $e = shift;
    # see documentation on TWiki::AccessControlException
} otherwise {
    ...
};

getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment )

Get revision info of a topic or attachment

• $web - Web name, optional, e.g. 'Main'
• $topic - Topic name, required, e.g. 'TokyoOffice'
• $rev - revsion number, or tag name (can be in the format 1.2, or just the minor number)
• $attachment -attachment filename

NOTE: if you are trying to get revision info for a topic, use $meta->getRevisionInfo instead if you can - it is significantly more efficient.

Since: TWiki::Plugins::VERSION 1.000 (29 Jul 2001)

getRevisionAtTime( $web, $topic, $time ) -> $rev

Get the revision number of a topic at a specific time.

• $web - web for topic
• $topic - topic
• $time - time (in epoch secs) for the rev

Since: TWiki::Plugins::VERSION 1.1

readTopic( $web, $topic, $rev ) -> ( $meta, $text )

Read topic text and meta data, regardless of access permissions.

• $web - Web name, required, e.g. 'Main'
• $topic - Topic name, required, e.g. 'TokyoOffice'
• $rev - revision to read (default latest)

$meta is a perl 'object' of class TWiki::Meta. This class is fully documented in the source code documentation shipped with the release, or can be inspected in the lib/TWiki/Meta.pm file.

This method ignores topic access permissions. You should be careful to use checkAccessPermissions to ensure the current user has read access to the topic.

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text

Read topic text, including meta data

• $web - Web name, e.g. 'Main', or empty
• $topic - Topic name, e.g. 'MyTopic', or "Main.MyTopic"
• $rev - Topic revision to read, optional. Specify the minor part of the revision, e.g. "5", not "1.5"; the top revision is returned if omitted or empty.
• $ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission

This method is more efficient than readTopic, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer.

Since: TWiki::Plugins::VERSION 1.010 (31 Dec 2002)

attachmentExists( $web, $topic, $attachment ) -> $boolean

Test if attachment exists

• $web - Web name, optional, e.g. Main.
• $topic - Topic name, required, e.g. TokyoOffice, or Main.TokyoOffice
• $attachment - attachment name, e.g.=logo.gif=

Since: TWiki::Plugins::VERSION 1.1

readAttachment( $web, $topic, $name, $rev ) -> $data

• $web - web for topic
• $topic - topic
• $name - attachment name
• $rev - revision to read (default latest)

View permission on the topic is required for the read to be successful. Access control violations are flagged by a TWiki::AccessControlException. Permissions are checked for the current user.

my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
my @attachments = $meta->find( 'FILEATTACHMENT' );
foreach my $a ( @attachments ) {
   try {
       my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
       ...
   } catch TWiki::AccessControlException with {
   };
}

Since: TWiki::Plugins::VERSION 1.1

saveAttachment( $web, $topic, $attachment, $opts )

• $web - web for topic
• $topic - topic to atach to
• $attachment - name of the attachment
• $opts - Ref to hash of options

Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.

    try {
        TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
                                     { file => 'image.gif',
                                       comment => 'Picture of Health',
                                       hide => 1 } );
   } catch Error::Simple with {
      # see documentation on Error
   } otherwise {
      ...
   };

Since: TWiki::Plugins::VERSION 1.1

moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )

• $web source web - required
• $topic source topic - required
• $attachment source attachment - required
• $newWeb dest web
• $newTopic dest topic
• $newAttachment dest attachment

The destination topic must already exist, but the destination attachment must not exist.

Rename an attachment to $TWiki::cfg{TrashWebName}.TrashAttament to delete it.

use Error qw( :try );

try {
   # move attachment between topics
   moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
                     "Countries", "France" );
   # Note destination attachment name is defaulted to the same as source
} catch TWiki::AccessControlException with {
   my $e = shift;
   # see documentation on TWiki::AccessControlException
} catch Error::Simple with {
   my $e = shift;
   # see documentation on Error::Simple
};

Since: TWiki::Plugins::VERSION 1.1

Assembling Pages

readTemplate( $name, $skin ) -> $text

Read a template or skin. Embedded template directives get expanded

• $name - Template name, e.g. 'view'
• $skin - Comma-separated list of skin names, optional, e.g. 'print'

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

loadTemplate ( $name, $skin, $web ) -> $text

• $name - template file name
• $skin - comma-separated list of skins to use (default: current skin)
• $web - the web to look in for topics that contain templates (default: current web)

Since: TWiki::Plugins::VERSION 1.1

Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.

How TWiki searches for templates is described in TWikiTemplates.

If template text is found, extracts include statements and fully expands them.

expandTemplate( $def ) -> $string

Do a , only expanding the template (not expanding any variables other than %TMPL)

• $def - template name

Since: TWiki::Plugins::VERSION 1.1

A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.

writeHeader( $query, $contentLength )

Prints a basic content-type HTML header for text/html to standard out

• $query - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should not pass this parameter)
• $contentLength - Length of content (optional, in most cases you should not pass this parameter)

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

redirectCgiQuery( $query, $url, $passthru )

Redirect to URL

• $query - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
• $url - URL to redirect to
• $passthru - enable passthrough.

Return: none

Print output to STDOUT that will cause a 302 redirect to a new URL. Nothing more should be printed to STDOUT after this method has been called.

The $passthru parameter allows you to pass the parameters that were passed to the current query on to the target URL, as long as it is another URL on the same TWiki installation. If $passthru is set to a true value, then TWiki will save the current URL parameters, and then try to restore them on the other side of the redirect. Parameters are stored on the server in a cache file.

Note that if $passthru is set, then any parameters in $url will be lost when the old parameters are restored. if you want to change any parameter values, you will need to do that in the current CGI query before redirecting e.g.

my $query = TWiki::Func::getCgiQuery();
$query->param(-name => 'text', -value => 'Different text');
TWiki::Func::redirectCgiQuery(
  undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

addToHEAD( $id, $header )

Adds $header to the HTML header (the tag). This is useful for Plugins that want to include some javascript custom css.

• $id - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
• $header - the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.

All TWiki variables present in $header will be expanded before being inserted into the section.

Note that this is not the same as the HTTP header, which is modified through the Plugins modifyHeaderHandler.

Since: TWiki::Plugins::VERSION 1.1

example:

TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')

expandCommonVariables( $text, $topic, $web, $meta ) -> $text

Expand all common %VARIABLES%

• $text - Text with variables to expand, e.g. 'Current user is %WIKIUSER%'
• $topic - Current topic name, e.g. 'WebNotify'
• $web - Web name, optional, e.g. 'Main'. The current web is taken if missing
• $meta - topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

See also: expandVariablesOnTopicCreation

renderText( $text, $web ) -> $text

Render text from TWiki markup into XHTML as defined in TWiki.TextFormattingRules

• $text - Text to render, e.g. '*bold* text and =fixed font='
• $web - Web name, optional, e.g. 'Main'. The current web is taken if missing

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text

Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by renderText()

• $pre - Text occuring before the TWiki link syntax, optional
• $web - Web name, required, e.g. 'Main'
• $topic - Topic name to link to, required, e.g. 'WebNotify'
• $label - Link label, required. Usually the same as $topic, e.g. 'notify'
• $anchor - Anchor, optional, e.g. '#Jump'
• $createLink - Set to '1' to add question linked mark after topic name if topic does not exist;
  set to '0' to suppress link for non-existing topics

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

E-mail

sendEmail ( $text, $retries ) -> $error

• $text - text of the mail, including MIME headers
• $retries - number of times to retry the send (default 1)

To: liz@windsor.gov.uk
From: serf@hovel.net
CC: george@whitehouse.gov
Subject: Revolution

Dear Liz,

Please abolish the monarchy (with King George's permission, of course)

Thanks,

A. Peasant

Since: TWiki::Plugins::VERSION 1.1

wikiToEmail( $wikiName ) -> $email

• $wikiname - wiki name of the user

Since: TWiki::Plugins::VERSION 1.1

Deprecated in favour of wikinameToEmails, because this function only returns a single email address, where a user may in fact have several.

Since TWiki 4.2.1, $wikiName may also be a login name.

Creating New Topics

expandVariablesOnTopicCreation ( $text ) -> $text

Expand the limited set of variables that are always expanded during topic creation

• $text - the text to process

Since: TWiki::Plugins::VERSION 1.1

Expands only the variables expected in templates that must be statically expanded in new content.

The expanded variables are:

• %DATE% Signature-format date
• %SERVERTIME% See TWikiVariables
• %GMTIME% See TWikiVariables
• %USERNAME% Base login name
• %WIKINAME% Wiki name
• %WIKIUSERNAME% Wiki name with prepended web
• %URLPARAM{...}% - Parameters to the current CGI query
• %NOP% No-op

See also: expandVariables

Special handlers

Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.

registerTagHandler( $var, \&fn, $syntax )

Should only be called from initPlugin.

Register a function to handle a simple variable. Handles both %VAR% and %VAR{...}%. Registered variables are treated the same as TWiki internal variables, and are expanded at the same time. This is a lot more efficient than using the commonTagsHandler.

• $var - The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name must match /^[A-Z][A-Z0-9_]*$/ or it won't work.
• \&fn - Reference to the handler function.
• $syntax can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard %MYVAR{ "unnamed" param1="value1" param2="value2" }% syntax, as well as an unquoted default parameter, such as %MYVAR{unquoted parameter}%. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR{param1=value1, value 2, param3="value 3", param4='value 5"}%

Since: TWiki::Plugins::VERSION 1.1

The variable handler function must be of the form:

sub handler(\%session, \%params, $topic, $web)

• \%session - a reference to the TWiki session object (may be ignored)
• \%params - a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with _DEFAULT being the name for the default parameter.
• $topic - name of the topic in the query
• $web - name of the web in the query

sub initPlugin{
   TWiki::Func::registerTagHandler('EXEC', \&boo);
}

sub boo {
    my( $session, $params, $topic, $web ) = @_;
    my $cmd = $params->{_DEFAULT};

    return "NO COMMAND SPECIFIED" unless $cmd;

    my $result = `$cmd 2>&1`;
    return $params->{silent} ? '' : $result;
}
}

Registered tags differ from tags implemented using the old TWiki approach (text substitution in commonTagsHandler) in the following ways:

• registered tags are evaluated at the same time as system tags, such as %SERVERTIME. commonTagsHandler is only called later, when all system tags have already been expanded (though they are expanded again after commonTagsHandler returns).
• registered tag names can only contain alphanumerics and _ (underscore)
• registering a tag FRED defines both %FRED{...}% and also %FRED%.
• registered tag handlers cannot return another tag as their only result (e.g. return '%SERVERTIME%';). It won't work.

registerRESTHandler( $alias, \&fn, )

Should only be called from initPlugin.

Adds a function to the dispatch table of the REST interface

• $alias - The name .
• \&fn - Reference to the function.

Since: TWiki::Plugins::VERSION 1.1

The handler function must be of the form:

sub handler(\%session)

• \%session - a reference to the TWiki session object (may be ignored)

From the REST interface, the name of the plugin must be used as the subject of the invokation.

Example

The EmptyPlugin has the following call in the initPlugin handler:

   TWiki::Func::registerRESTHandler('example', \&restExample);

This adds the restExample function to the REST dispatch table for the EmptyPlugin under the 'example' alias, and allows it to be invoked using the URL

http://server:port/bin/rest/EmptyPlugin/example

note that the URL

http://server:port/bin/rest/EmptyPlugin/restExample

(ie, with the name of the function instead of the alias) will not work.

decodeFormatTokens($str) -> $unencodedString

TWiki has an informal standard set of tokens used in format parameters that are used to block evaluation of paramater strings. For example, if you were to write

%MYTAG{format="%WURBLE%"}%

then %WURBLE would be expanded before %MYTAG is evaluated. To avoid this TWiki uses escapes in the format string. For example:

%MYTAG{format="$percntWURBLE$percnt"}%

This lets you enter arbitrary strings into parameters without worrying that TWiki will expand them before your plugin gets a chance to deal with them properly. Once you have processed your tag, you will want to expand these tokens to their proper value. That's what this function does.

Note thath $quot, $percnt and $dollar all work *even if they are followed by alphanumeric characters*. You have been warned!

Since: TWiki::Plugins::VERSION 1.2

Searching

searchInWebContent($searchString, $web, \@topics, \%options ) -> \%map

Search for a string in the content of a web. The search is over all content, including meta-data. Meta-data matches will be returned as formatted lines within the topic content (meta-data matches are returned as lines of the format %META:\w+{.*}%)

• $searchString - the search string, in egrep format
• $web - The web to search in
• \@topics - reference to a list of topics to search
• \%option - reference to an options hash

• type - if regex will perform a egrep-syntax RE search (default '')
• casesensitive - false to ignore case (defaulkt true)
• files_without_match - true to return files only (default false). If files_without_match is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).

The return value is a reference to a hash which maps each matching topic name to a list of the lines in that topic that matched the search, as would be returned by 'grep'.

To iterate over the returned topics use:

my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
   { casesensitive => 0, files_without_match => 0 } );
foreach my $topic (keys %$result ) {
   foreach my $matching_line ( @{$result->{$topic}} ) {
      ...etc

Since: TWiki::Plugins::VERSION 1.1

Plugin-specific file handling

getWorkArea( $pluginName ) -> $directorypath

Gets a private directory for Plugin use. The Plugin is entirely responsible for managing this directory; TWiki will not read from it, or write to it.

The directory is guaranteed to exist, and to be writable by the webserver user. By default it will not be web accessible.

The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.

Since: TWiki::Plugins::VERSION 1.1 (Dec 2005)

readFile( $filename ) -> $text

Read file, low level. Used for Plugin workarea.

• $filename - Full path name of file

NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.

Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)

saveFile( $filename, $text )

Save file, low level. Used for Plugin workarea.

• $filename - Full path name of file
• $text - Text to save

NOTE: Use this function only for the Plugin workarea, not for topics and attachments. Use the appropriate functions to manipulate topics and attachments.

Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)

General Utilities

getRegularExpression( $name ) -> $expr

Retrieves a TWiki predefined regular expression or character class.

• $name - Name of the expression to retrieve. See notes below

Since: TWiki::Plugins::VERSION 1.020 (9 Feb 2004)

Note: TWiki internally precompiles several regular expressions to represent various string entities in an I18N-compatible manner. Plugins authors are encouraged to use these in matching where appropriate. The following are guaranteed to be present. Others may exist, but their use is unsupported and they may be removed in future TWiki versions.

In the table below, the expression marked type 'String' are intended for use within character classes (i.e. for use within square brackets inside a regular expression), for example:

   my $upper = TWiki::Func::getRegularExpression('upperAlpha');
   my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
   my $capitalized = qr/[$upper][$alpha]+/;

   my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
   my $isWebName = ( $s =~ m/$webRE/ );

normalizeWebTopicName($web, $topic) -> ($web, $topic)

Parse a web and topic name, supplying defaults as appropriate.

• $web - Web name, identifying variable, or empty string
• $topic - Topic name, may be a web.topic string, required.

Since: TWiki::Plugins::VERSION 1.1

Note that hierarchical web names (SubWeb ) are only available if hierarchical webs are enabled in configure.

The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:

StaticMethod *sanitizeAttachmentName ($fname) -> ($fileName,$origName)

Given a file namer, sanitise it according to the rules for transforming attachment names. Returns the sanitised name together with the basename before sanitisation.

Sanitation includes filtering illegal characters and mapping client file names to legal server names.

Since: TWiki::Plugins::VERSION 1.2

spaceOutWikiWord( $word, $sep ) -> $text

Spaces out a wiki word by inserting a string (default: one space) between each word component. With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.

Since: TWiki::Plugins::VERSION 1.2

writeWarning( $text )

Log Warning that may require admin intervention to data/warning.txt

• $text - Text to write; timestamp gets added

Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

writeDebug( $text )

Log debug message to data/debug.txt

• $text - Text to write; timestamp gets added

Since: TWiki::Plugins::VERSION 1.020 (16 Feb 2004)

formatTime( $time, $format, $timezone ) -> $text

Format the time in seconds into the desired time string

• $time - Time in epoc seconds
• $format - Format type, optional. Default e.g. '31 Dec 2002 - 19:30'. Can be '$iso' (e.g. '2002-12-31T19:30Z'), '$rcs' (e.g. '2001/12/31 23:59:59', '$http' for HTTP header format (e.g. 'Thu, 23 Jul 1998 07:21:56 GMT'), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz' for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
• $timezone - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'

Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)

isTrue( $value, $default ) -> $boolean

Returns 1 if $value is true, and 0 otherwise. "true" means set to something with a Perl true value, with the special cases that "off", "false" and "no" (case insensitive) are forced to false. Leading and trailing spaces in $value are ignored.

If the value is undef, then $default is returned. If $default is not specified it is taken as 0.

Since: $TWiki::Plugins::VERSION 1.2

isValidWikiWord ( $text ) -> $boolean

Check for a valid WikiWord or WikiName

• $text - Word to test

Since: TWiki::Plugins::VERSION 1.100 (Dec 2005)

extractParameters($attr ) -> %params

Extract all parameters from a variable string and returns a hash of parameters

• $attr - Attribute string

Since: TWiki::Plugins::VERSION 1.025 (26 Aug 2004)

• Example:
  • Variable: %TEST{ 'nameless' name1="val1" name2="val2" }%
  • First extract text between {...} to get: 'nameless' name1="val1" name2="val2"
  • Then call this on the text:
    
• params = TWiki::Func::extractParameters( $text );=
  • The %params hash contains now:
    _DEFAULT => 'nameless'
name1 => "val1"
name2 => "val2"

extractNameValuePair( $attr, $name ) -> $value

Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters

• $attr - Attribute string
• $name - Name, optional

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

• Example:
  • Variable: %TEST{ 'nameless' name1="val1" name2="val2" }%
  • First extract text between {...} to get: 'nameless' name1="val1" name2="val2"
  • Then call this on the text:
    my $noname = TWiki::Func::extractNameValuePair( $text );
my $val1  = TWiki::Func::extractNameValuePair( $text, "name1" );
my $val2  = TWiki::Func::extractNameValuePair( $text, "name2" );

Deprecated functions

From time-to-time, the TWiki developers will add new functions to the interface (either to TWikiFuncDotPm, or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.

Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %FAILEDPLUGINS%.

This is done by defining a map from the handler name to the TWiki::Plugins version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler for compatibility with TWiki::Plugins versions before 1.1, we would add this to the plugin:

package TWiki::Plugins::SinkPlugin;
use vars qw( %TWikiCompatibility );
$TWikiCompatibility{endRenderingHandler} = 1.1;

The following functions are retained for compatibility only. You should stop using them as soon as possible.

getScriptUrlPath( ) -> $path

Get script URL path

DEPRECATED since 1.1 - use getScriptUrl instead.

Return: $path URL path of TWiki scripts, e.g. "/cgi-bin"

WARNING: you are strongly recommended not to use this function, as the {ScriptUrlPaths} URL rewriting rules will not apply to urls generated using it.

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url

Compose fully qualified 'oops' dialog URL

• $web - Web name, e.g. 'Main'. The current web is taken if empty
• $topic - Topic name, e.g. 'WebNotify'
• $template - Oops template name, e.g. 'oopsmistake'. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
• $param1 ... $param4 - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional

DEPRECATED since 1.1, the recommended approach is to throw an oops exception.

   use Error qw( :try );

   throw TWiki::OopsException(
      'toestuckerror',
      web => $web,
      topic => $topic,
      params => [ 'I got my toe stuck' ]);

If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use getScriptUrl instead:

   my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
            template => 'oopstoestuckerror',
            param1 => 'I got my toe stuck');
   TWiki::Func::redirectCgiQuery( undef, $url );
   return 0;

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

permissionsSet( $web ) -> $boolean

Test if any access restrictions are set for this web, ignoring settings on individual pages

• $web - Web name, required, e.g. 'Sandbox'

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

DEPRECATED since 1.2 - use getPreferencesValue instead to determine what permissions are set on the web, for example:

foreach my $type qw( ALLOW DENY ) {
    foreach my $action qw( CHANGE VIEW ) {
        my $pref = $type . 'WEB' . $action;
        my $val = getPreferencesValue( $pref, $web ) || '';
        if( $val =~ /\S/ ) {
            print "$pref is set to $val on $web\n";
        }
    }
}

getPublicWebList( ) -> @webs

DEPRECATED since 1.1 - use getListOfWebs instead.

Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences

Return: @webs List of all public webs, e.g. ( 'Main',  'Know', 'TWiki' )

Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)

formatGmTime( $time, $format ) -> $text

DEPRECATED since 1.1 - use formatTime instead.

Format the time to GM time

• $time - Time in epoc seconds
• $format - Format type, optional. Default e.g. '31 Dec 2002 - 19:30', can be 'iso' (e.g. '2002-12-31T19:30Z'), 'rcs' (e.g. '2001/12/31 23:59:59', 'http' for HTTP header format (e.g. 'Thu, 23 Jul 1998 07:21:56 GMT')

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

getDataDir( ) -> $dir

DEPRECATED since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead

Get data directory (topic file root)

Return: $dir Data directory, e.g. '/twiki/data'

This function violates store encapsulation and is therefore deprecated.

Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)

getPubDir( ) -> $dir

DEPRECATED since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead

Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName

Return: $dir Pub directory, e.g. '/htdocs/twiki/pub'

This function violates store encapsulation and is therefore deprecated.

Use readAttachment and saveAttachment instead.

Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)

checkDependencies( $moduleName, $dependenciesRef ) -> $error

DEPRECATED since 1.1 - use TWiki:Plugins.BuildContrib and define DEPENDENCIES that can be statically evaluated at install time instead. It is a lot more efficient.

Since: TWiki::Plugins::VERSION 1.025 (01 Aug 2004)

Back to top

TWiki CGI and Command Line Scripts

Programs on the TWiki server performing actions such as rendering, saving and renaming topics.

The TWiki scripts are located in the twiki/bin and twiki/tools directories. This topic describes the interfaces to some of those scripts. All scripts in the twiki/bin directory can be called from the CGI (Common Gateway Interface) environment or from the command line. The scripts in the twiki/tools directory can only be called from the command line.

CGI Scripts

General Information

CGI environment

Command-line

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"

Common parameters

attach

changes

The changes script can receive one parameter:

The main difference between invoking this script and using WebChanges is that WebChanges is based on a %SEARCH%, while this script reads the changes file in each web, making it much faster.

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

edit

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.

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.

login

logon

manage

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

action=createweb

action=renameweb

action=editSettings

action=saveSettings

action=bulkRegister

action=changePassword

action=resetPassword

This is used by BulkResetPassword and ResetPassword. Only administrators can provide a list of LoginNames, non-admins can only provide a single LoginName.

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.

action=deleteUserAccount

oops

oops templates are used with the oops script to generate system messages. This is done to make internationalisation or other local customisations simple.

The oops script supports the following parameters:

preview

rdiff

• add a {word} render style

register

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.

rename

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.

rest

Representational State Transfer

The rest script supports the following parameters:

The function is free to use any other query parameters for its own purposes.

Note: 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

The rest script assumes that it will be called with URL in the form:

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

As an example, the EmptyPlugin has registered a function to be used with the rest script under the subject EmptyPlugin and the verb example. Click below to see the rest script in action (run as TWikiGuest).

Call the Plugin

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

save

Any errors will cause a redirect to an oops page.

The parameters are interpreted in according to the following rules.

1. The first sequence of ten or more X characters in the topic name will be converted to a number such that the resulting topic name is unique in the target web.
2. When the action is save, checkpoint, quietsave, or preview:
   1. The new text is taken from the text parameter, if it is defined,
      • otherwise it is taken from the templatetopic, if it is defined, (new topic only)
      • otherwise it is taken from the previous version of the topic, if any,
   2. The name of the new form is taken from the formtemplate, if defined
      • otherwise it is taken from the templatetopic, if defined, (new topic only)
      • otherwise it is taken from the previous version of the topic, if any,
      • otherwise no form is attached.
   3. The value for each field in the form is taken from the query, if it is defined
      • otherwise it is taken from the templatetopic, if defined, (new topic only)
      • otherwise it is taken from the previous version of the topic, if any,
      • otherwise it defaults to the empty string.

Merging is only enabled if the topic text comes from text and originalrev is > 0 and is not the same as the revision number of the most recent revision. If merging is enabled both the topic and the meta-data are merged.

Form field values are passed in parameters named 'field' - for example, if I have a field Status the parameter name is Status.

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

<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post">
    ...
</form>

search

Parameter:	Description:	Default:
search="text"	(Alternative to above)	N/A
bookview="on"	BookView search, e.g. show complete topic text	Show topic summary
casesensitive="on"	Case sensitive search	Ignore case
web="Name" web="Main, Know" web="all"	Comma-separated list of webs to search. See TWikiVariables#VarSEARCH for more details.	Current web
header="..." format="..."	Custom format results: see FormattedSearch for usage, variables & examples	Results in table
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)
nototal="on"	Do not show number of topics found	Show number
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
expandvariables="on"	Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula	Raw text
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
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
limit="all" limit="16"	Limit the number of results returned. This is done after sorting if order is specified	All results
date="..."	limits the results to those pages with latest edit time in the given time interval.	All results
separator=", "	Line separator between hits	Newline "$n"
multiple="on"	Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search	Only one hit per topic
reverse="on"	Reverse the direction of the search	Ascending search
"text"	Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more	required
scope="topic" scope="text" scope="all"	Search topic name (title); the text (body) of topic; or all (both)	"text"
nonoise="on"	Shorthand for nosummary="on" nosearch="on" nototal="on" zeroresults="off" noheader="on" noempty="on"	Off
nosummary="on"	Show topic title only	Show topic summary
order="topic" order="created" order="modified" order="editby" order=  "formfield(name)"	Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort	Sort by topic name
zeroresults="off"	Suppress all output if there are no hits	zeroresults="on", displays: "Number of topics: 0"
noempty="on"	Suppress results for webs that have no hits.	Show webs with no hits
noheader="on"	Suppress search header Topics: Changed: By:	Show search header
nosearch="on"	Suppress search string	Show search string

statistics

for example:

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

upload

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.

view

Parameter	Description	Default
raw=on	Shows the text of the topic in a scrollable textarea
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 https://wiki.planta.de/twiki/bin/view/TWiki_/TWikiScripts?template=edit. This is mainly useful when you have specialised templates for a TWiki Application.
topic	redirects (at the beging of the cgi script running) to show the spcified Web.Topic, or, redirects to a URL, if allowed by {AllowRedirectUrl} and {PermittedRedirectHostUrls}

For historical reasons, the view script has a special interpretation of the text skin. In earlier TWiki versions the skin=text parameter was used like this: http://.../view/MyWeb/MyTopic?skin=text&contenttype=text/plain&raw=on 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.

viewfile

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://wiki.planta.de/twiki/bin/viewfile/Webname/TopicName/Attachment.gif

Command Line Scripts

geturl.pl

• 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

tick_twiki.pl

It is intended to be run as a cron job or a scheduled task once a week. Example crontab entry:
0 0 * * 0 cd /usr/twiki/bin && perl ../tools/tick_twiki.pl

Note: The script has to be run by a user who can write files created by the webserver user.

Related Topics: AdminDocumentationCategory, DeveloperDocumentationCategory

Back to top

TWiki Site Tools

Utilities for searching, navigation, and monitoring site activity

TWiki Site Tools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools, WebNotify, to e-mail alerts when topics are edited, and WebStatistics, to generate detailed activity reports.

WebNotify - recent changes alert

Each TWiki web has an automatic e-mail alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using WebNotify in each web. The Perl script mailnotify is called by a background process at regular intervals. The script sends an automated e-mail to subscribed users if topics were changed in a web since the script was last run.

• You can create a WebNotify link using TWikiVariables with %NOTIFYTOPIC%

Web Changes Notification Service

Each TWiki web has an automatic e-mail notification service that sends you an e-mail with links to all of the topics modified since the last alert.

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole groups of users can also be subscribed for notification.

The general format of a subscription is:

three spaces * subscriber [ : topics ]