TWiki Variables

Special text strings expand on the fly to display dynamic content, such as user data or system info

TWikiVariables are text strings - %VARIABLE% or %VARIABLE{ parameter="value" }% - that expand into content whenever a topic is rendered for viewing. There are two types of variables:

1. Preferences variables: Can be defined and changed by the user.
   Example: %T% renders as
2. Predefined variables: Defined by the TWiki system or by extensions.
   Example: %CALCULATE{}% is handled by the SpreadSheetPlugin

See list of all TWiki Variables currently defined in this TWiki installation.

TWiki Variables Wizard — to Find and Compose Variables

Categories: all Administration Applications & Components Attachments & Files Charting & Drawing Database & Forms Date & Time Development Editing & Content Update Email & Notification Export & Publishing Formatting & Rendering Import Linking & Navigation Searching & Listing Security & Access Control Skins & Templates System Information Tables & Spreadsheets UI& Visualization Users & Authentication Workflow & Automation

Variables:

Pre-load image:

<--
-->

<--
-->

Using Variables

To use a variable type its name. For example,

• type %T% to get (a preferences variable)
• type %TOPIC% to get TWikiVariables (a predefined variable)
• type %CALCULATE{ "$UPPER(Text)" }% to get TEXT (a variable defined by a plugin)

Note:

• To leave a variable unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%
• Variables are expanded relative to the topic they are used in, not the topic they are defined in
• Type %ALLVARIABLES% to get a full listing of all variables defined for a particular topic

Variable Names

Variable names must start with a letter, optionally followed by letters, numbers and underscore '_' characters. Both upper-case and lower-case characters can be used, %MYVAR%, %MyVar%, %My2ndVar%, and %My_Var% are valid names. Variables are case sensitive, e.g. %MyVAR% and %MYVAR% are not the same.

By convention all settings, predefined variables and variables handled by extensions are always UPPER-CASE.

Preferences Variables

Unlike predefined variables, preferences variables can be defined by the user in various places.

Setting Preferences Variables

You can set variables in all the following places:

1. system level in TWiki.TWikiPreferences
2. plugin topics (see TWikiPlugins)
3. local site level in Main.TWikiPreferences
4. user level in individual user topics in Main web
   • If UserSubwebs is in effect, the topic specified by %USERPREFSTOPIC% in the user's subweb is read instead
   • If $TWiki::cfg{DemoteUserPreferences} is true, this step is deferred to a later step. On this TWiki installation, $TWiki::cfg{DemoteUserPreferences} is false
5. web level in WebPreferences of each web
6. If EXTRAPREFERENCES is defined at this point, it's regarded as having comma separated list of topics. Those topics are read in the listed order as if they were WebPreferences
7. topic level in topics in webs
8. session variables (if sessions are enabled)
9. user level preferences are set at this point if $TWiki::cfg{DemoteUserPreferences} is true as mentioned at the step 4

Settings at higher-numbered levels override settings of the same variable at lower numbered levels, unless the variable was included in the setting of FINALPREFERENCES at a lower-numbered level, in which case it is locked at the value it has at that level.

If you are setting a variable and using it in the same topic, note that TWiki reads all the variable settings from the saved version of the topic before it displays anything. This means you can use a variable anywhere in the topic, even if you set it somewhere inconspicuous near the end. But beware: it also means that if you change the setting of a variable you are using in the same topic, preview will show the wrong thing, and you must save the topic to see it correctly.

The syntax for setting variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets):
[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value

Examples:

   * Set VARIABLENAME1 = value
      * Set VARIABLENAME2 = value

Spaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line.

Example:

   * Set VARIABLENAME = value starts here
     and continues here

Whatever you include in your variable will be expanded on display, exactly as if it had been entered directly.

Example: Create a custom logo variable

• To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences topic, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. LogoTopic. Sample variable setting in WebPreferences:

      * Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif

You can also set preferences variables on a topic by clicking the link Edit topic preference settings under More topic actions. Use the same * Set VARIABLENAME = value syntax. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.

Controlling User Level Preferences Override

By default, user level variables are set at the step 4 as stated in the previous section. That means a user can finalise some preferences variables so that web level or topic level setting cannot override it. This may result in a situation the web or page owner doesn't expect. $TWiki::cfg{DemoteUserPreferences} has been introduced to avoid it. If it's set to true, user level variables are set at the last step instead of the step 4.

But this is not enough. To guarantee a certain result, you need to finalise critical preferences variables set at the web or topic level, which is cumbersome. So preferences variables DENYUSERPREFEENCES and ALLOWUSERPREFEENCES have been introduced.

• DENYUSERPREFEENCES and ALLOWUSERPREFEENCES may have comma separated list of variable names
• If a preferences variable is listed in DENYUSERPREFEENCES, the variable cannot be overridden at the user level. There is a special value "all", which means no preferences variables can be overridden at the user level
• If ALLOWUSERPREFEENCES is set and not empty, only the listed preferences variables can be overridden. There is a special value "all", which means any preferences variable can be overridden at the user level. But actually, "all" is not necessary since a blank value or not setting ALLOWUSERPREFEENCES has the same effect
• DENYUSERPREFEENCES takes precedence over ALLOWUSERPREFEENCES. If a variable is listed on both, it cannot be overridden. If DENYUSERPREFEENCES is "all", the value of ALLOWUSERPREFEENCES doesn't matter.

   * Set DENYUSERPREFERENCES = all

   * Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

   * Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

You will get the most benefit of DENYUSERPREFEENCES and ALLOWUSERPREFEENCES by setting $TWiki::cfg{DemoteUserPreferences} to true. That way, each web can specify how much user level preferences overriding is allowed.

Parameterized Variables (Macros)

It is possible to pass parameters to TWiki variables. This is called a macro in a programming language.

To define a parameterized variable, set a variable that contains other variables, such as:

   * Set EXAMPLE = Example variable using %DEFAULT%, %PARAM1% and %PARAM2%
   * Set DEMO = Demo using %DEFAULT{ default="(undefined)" }%,
                %PARAM1{ default="(undefined)" }% and %PARAM2{ default="(undefined)" }%

A special %DEFAULT% variable denotes the default (nameless) parameter of the calling variable. Variables optionally may list a default="..." parameter that gets used in case the calling variable does not specify that parameter.

To use a parameterized variable (or call a macro), add parameters within the curly brackets, such as:

   * %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }%
   * %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missing

• %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }%
• %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missing

Parameters in the variable definition are expanded using the following sequence:

1. Parameter from variable call. In above example, %PARAM1% gets expanded to bar.
2. Session variable and preferences settings

Example

Define variables:

   * Set DRINK = red wine
   * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%,
                    my %DEFAULT{default="favorite"}% drink is %DRINK%.

Use Variables:

%FAVORITE{ DISH="Sushi" DRINK="Sake" }%

%FAVORITE{}%

%FAVORITE{ "preferred" }%

<--
Redefine what is defined in INCLUDE: 

 Set EXAMPLE = Example variable using favorite, (undefined) and (undefined)
 
 Set DEMO = Demo using favorite,                (undefined) and (undefined)
 
 Set DRINK = red wine
 
 Set FAVORITE = My favorite dish is steak,                    my favorite drink is %DRINK%.
 
-->

Access Control Variables

These are special types of preferences variables to control access to content. TWikiAccessControl explains these security settings in detail.

Local values for variables

Certain topics (a users home topic, web site and default preferences topics) have a problem; variables defined in those topics can have two meanings. For example, consider a user topic. A user may want to use a double-height edit box when they are editing their home topic - but only when editing their home topic. The rest of the time, they want to have a normal edit box. This separation is achieved using Local in place of Set in the variable definition. For example, if the user sets the following in their home topic:

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20

Use this powerful feature with great care! %ALLVARIABLES% can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.

Frequently Used Preferences Variables

The following preferences variables are frequently used. They are defined in TWikiPreferences#Miscellaneous_Settings:

• %BB% - line break and bullet combined
• %BB2% - level 2 bullet with line break
• %BB3% - level 3 bullet with line break
• %BB4% - level 4 bullet with line break
• %BR% - line break
• %BULLET% - bullet sign
• %CARET% - caret symbol
• %VBAR% - vertical bar
• %H% - Help icon
• %I% - Idea icon
• %M% - Moved to icon
• %N% - New icon
• %P% - Refactor icon
• %Q% - Question icon
• %S% - Pick icon
• %T% - Tip icon
• %U% - Updated icon
• %X% - Alert icon
• %Y% - Done icon
• %RED% text %ENDCOLOR% - colored text (also %YELLOW%, %ORANGE%, %PINK%, %PURPLE%, %TEAL%, %NAVY%, %BLUE%, %AQUA%, %LIME%, %GREEN%, %OLIVE%, %MAROON%, %BROWN%, %BLACK%, %GRAY%, %SILVER%, %WHITE%)
• %REDBG% text %ENDBG% - colored background (also %YELLOWBG%, %ORANGEBG%, %PINKBG%, %PURPLEBG%, %TEALBG%, %NAVYBG%, %BLUEBG%, %AQUABG%, %LIMEBG%, %GREENBG%, %OLIVEBG%, %MAROONBG%, %BROWNBG%, %BLACKBG%, %GRAYBG%, %SILVERBG%, %WHITEBG%)

There are additional useful preferences variables defined in TWikiPreferences, in Main.TWikiPreferences, and in WebPreferences of every web.

Predefined Variables

Most predefined variables return values that were either set in the configuration when TWiki was installed, or taken from server info (such as current username, or date and time). Some, like %SEARCH%, are powerful and general tools.

• Show all TWiki Variables
• Predefined variables can be overridden by preferences variables (except a few such as TOPIC and WEB)
  • This has long been the case but may not be desirable since even something as fundamental as %IF{...}%, %SCRIPT{...}%, and %INCLUDE{...}% can be overridden
  • So TWiki-6.0.1 has introduced a way to protect predefined variables from being overridden by preferences variables
  • The preferences variable OVERRIDABLEPREDEFINEDVARIABLES having a comma separated list of predefined variables specifies which predefined variables are overridable
  • By default, it's set to "all" (set at TWiki.TWikiPreferences), which means any predefined variable can be overridden, which is for compatibility with prior releases. You can set it to a different value in Main.TWikiPreferences and you may finalise it
  • If it's set as below, all predefined variables are protected

       * Set OVERRIDABLEPREDEFINEDVARIABLES =
    

  • If it's set as below, DATE and LANGUAGE predefined variables can be overridden but all the other predefined variables cannot

       * Set OVERRIDABLEPREDEFINEDVARIABLES = DATE, LANGUAGE
    

• Extensions may extend the set of predefined variables (see individual extension topics for details)
• Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.

Search or List Variables by Category

All TWiki Variables: ACTIVATEDPLUGINS, ADDTOHEAD, ALLVARIABLES, AQUA, ATTACHURL, ATTACHURLPATH, AUTHREALM, BASETOPIC, BASEWEB, BB, BB2, BB3, BB4, BLACK, BLUE, BR, BROWN, BUBBLESIG, BULLET, CALC, CALCULATE, CARET, CHILDREN, COLORPICKER, COMMENT, CONTENTMODE, COPY, DASHBOARD, DATE, DATEPICKER, DISPLAYTIME, DISPLAYTIME2, EDITACTION, EDITFORMFIELD, EDITTABLE, ENCODE, ENDBG, ENDCOLOR, ENDCOLUMNS, ENDSECTION, ENTITY, ENV, EXAMPLEVAR, FAILEDPLUGINS, FORMFIELD, FOURCOLUMNS, GET, GMTIME, GMTIME2, GRAY, GREEN, GROUPS, H, HEADLINES, HIDE, HIDEINPRINT, HOMETOPIC, HTTP, HTTPHOST, HTTPS, I, ICON, ICONURL, ICONURLPATH, IF, INCLUDE, INCLUDINGTOPIC, INCLUDINGWEB, JQENDTAB, JQENDTABPANE, JQTAB, JQTABPANE, LANGUAGE, LANGUAGES, LAQUO, LIME, LOCALSITEPREFS, LOGIN, LOGINURL, LOGOUT, LOGOUTURL, M, MAINWEB, MAKETEXT, MAROON, MDREPO, META, METASEARCH, N, NAVY, NBSP, NOP, NOTIFYTOPIC, OLIVE, ORANGE, P, PARENTBC, PARENTTOPIC, PINK, PLUGINDESCRIPTIONS, PLUGINVERSION, PUBURL, PUBURLPATH, PURPLE, Q, QUERYPARAMS, QUERYSTRING, RAQUO, RED, REDBG, REG, REMOTEADDR, REMOTEPORT, REMOTEUSER, RENDERLIST, REVINFO, REVINFO2, S, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURL2, SCRIPTURLPATH, SCRIPTURLPATH2, SEARCH, SERVERTIME, SERVERTIME2, SESSIONID, SESSIONVAR, SESSIONVARIABLE, SET, SETGETDUMP, SILVER, SITENAME, SITESTATISTICSTOPIC, SLIDESHOWEND, SLIDESHOWSTART, SPACEDTOPIC, SPACEOUT, STARTINCLUDE, STARTSECTION, STATISTICSTOPIC, STOPINCLUDE, SYSTEMWEB, T, TABLE, TEAL, THREECOLUMNS, TM, TOC, TOC2, TOPIC, TOPICLIST, TOPICTITLE, TOPICURL, TWIKIWEB, TWISTY, TWOCOLUMNS, U, URLPARAM, USERINFO, USERNAME, USERREPORT, USERSIG, USERSWEB, VAR, VBAR, WEB, WEBLIST, WEBPREFSTOPIC, WHITE, WIKIHOMEURL, WIKILOGOALT, WIKILOGOIMG, WIKILOGOURL, WIKINAME, WIKIPREFSTOPIC, WIKITOOLNAME, WIKIUSERNAME, WIKIUSERSTOPIC, WIKIVERSION, WIP, X, Y, YELLOW, total 185 variables

Documenting TWiki Variables

This section is for people documenting TWiki variables of the TWiki core and TWiki extensions.

Each variable is documented in a topic named Var<name> in the TWiki web. For example, a %LIGHTSABER% variable has a documentation topic called VarLIGHTSABER. The topic is expected to have a specific format so that reports in this TWikiVariables topic, in TWikiVariablesSearch and in category topics work as expected.

Basic structure of a variable documentation topic:

• Parent set to TWikiVariables
• An anchor named the same like the topic, such as #VarLIGHTSABER
• A ---+++ (level 3) heading with variable name, --, short description
• A bullet with description of the variable (optional)
• A Syntax: bullet with example syntax
• A Parameters: bullet with a table explaining the parameters (optional)
• An Example: bullet or two with examples
• An Expands to: bullet with expanded variable (optional)
• A Note: bullet with notes (optional)
• A Category: bullet with one or more of the TWiki variables categories:
  AdministrationVariables, ApplicationsAndComponentsVariables, AttachmentsAndFilesVariables, ChartingAndDrawingVariables, DatabaseAndFormsVariables, DateAndTimeVariables, DevelopmentVariables, EditingAndContentUpdateVariables, EmailAndNotificationVariables, ExportAndPublishingVariables, FormattingAndRenderingVariables, ImportVariables, LinkingAndNavigationVariables, SearchingAndListingVariables, SecurityAndAccessControlVariables, SkinsAndTemplatesVariables, SystemInformationVariables, TablesAndSpreadsheetsVariables, UIAndVisualizationVariables, UsersAndAuthenticationVariables, WorkflowAndAutomationVariables
• A Related: bullet with related links. Links have conditional IF so that links work properly locally in variable documentation topics and in the TWikiVariables topic

Example content of a VarLIGHTSABER topic:

#VarLIGHTSABER
---+++ LIGHTSABER -- laser sword to fend of unethical competition
   * The =%<nop>LIGHTSABER{}%= variable is handled by the LightsaberPlugin.
   * Syntax: =%<nop>LIGHTSABER{ _parameters_ }%=
   * Parameters:
     | *Parameter* | *Description* | *Default* |
     | =color="..."= | Color: =red=, =glue=, =green= | =white= |
     | =sound="..."= | Sound: =none=, =standard=, =loud= | =none= |
   * Example: =%<nop>LIGHTSABER{ color="red" }%= shows a red Lightsaber
   * Expands to: =%LIGHTSABER{ color="red" }%=
   * Note: The Lightsaber is a fictional weapon in the Star Wars universe, a "laser sword."
   * Category: FormattingAndRenderingVariables, UIAndVisualizationVariables
   * Related: [[%IF{"'%INCLUDINGTOPIC%'='TWikiVariables'" then="#"}%VarPLASMA][PLASMA]], LightsaberPlugin

TWiki Forms - Foundation of TWiki Applications

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 free form 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

Tip: The blog How to Create a TWiki Application on TWiki.org is a good tutorial to get started with TWiki forms based applications.

Defining a Form

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.

1. Create a new topic with your form name: YourForm, ExpenseReportForm, InfoCategoryForm, RecordReviewForm, whatever you need.
   The name of a Form Template topic must end in Form.
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

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.

Adding a Form to a Topic

• To add a Form, follow the "More topic actions" link at the bottom of a topic, select "Add or Replace Form".
  • Select a Form Template topic. These are topics with names ending in Form that contain a Form Template table.
  • A Form is typically added to a template topic, either to the WebTopicEditTemplate topic in a web, or a new topic that serves as an application specific template topic.
  • Modify the template topic to set the initial Form values.

• 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

• To change a Form, follow the "More topic actions" link at the bottom of a topic, select "Add or Replace Form", and select a new 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 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 row of the table defines one element of an input field:

The Name, Type and Size columns are required. Other columns are optional. The form template must have a header row, e.g. at least | *Name* | *Type* | *Size* | is required. Columns:

• Name column: Name is the name of the form field.

• Type, Size, Value columns: Type, Size and Value describe the type, size and initial value of this form field. Type text, checkbox, select and more are described in the Form Field Types section below.

• Tooltip message column: The Tooltip message will be displayed when the cursor is hovered over the field in edit view.

• Attributes column: Attributes may contain additional key="value" form field attributes, separated by space.
  • A hidden="1" attribute indicates that this field is hidden, e.g. not shown in view mode. However, the field is available for editing and storing information. The deprecated H attribute has the same function, it is still supported but might be removed in a future TWiki release.
    Tip: The TWiki form header is suppressed in view mode if all fields of the form are hidden. For better usability it is good to hide the whole form if the display and interaction of all form fields is done externally. For example, the display and modification of form field values can be done in a header topic that is included in each page.
  • An mandatory="1" attribute 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. The deprecated M attribute has the same function, it is still supported but might be removed in a future TWiki release.
  • Additional form field type specific attributes can be used, such as onfocus="..." and spellcheck="..".

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 Name Notes:

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

Field Value Notes:

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

General Notes:

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

Form Field Types

Each table row of a form template defines one element of an input field:

Many types of form fields are available. Some are TWiki internal, some are provided by extensions. Find more TWiki form field extensions on TWiki.org. The Size, Value and Attributes depend on the Type used. Form field types:

Type	Description	Size	Value
text	One-line text field	Text box width in number of characters	Initial (default) content
textarea	Multi-line text box	Columns x rows, such as 80x6; default is 40x5	Initial (default) content
label	Read-only text label		Text of the label
checkbox	One or more checkboxes that can be toggled individually	Number of checkboxes shown per line	Comma-space-separated list of item labels - can be a dynamic SEARCH
checkbox+buttons	Like checkbox, adding [Set] and [Clear] buttons
radio	Radio buttons, mutually exclusive; only one can be selected	Number of radio buttons shown per line	Comma-space-separated list of item labels - can be a dynamic SEARCH
combobox	Text field & select combination box, rendered as a text input field and a button to open up a selector box	Text box width in number of characters	Comma-space-separated list of options of the select box - can be a dynamic SEARCH
select	Select box, rendered as a picklist or a multi-row selector box depending on the size value	• 1: Show a picklist • Number > 1: Multi-row selector box of specified size • Range e.g. 3..10: Multi-row selector box with variable size - the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options	Comma-space-separated list of options of the select box - can be a dynamic SEARCH
select+multi	Like select, turning multi-select on, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items
select+values	Like select, allowing definition of values that are different to the displayed text. An option is defined as value: title, where the value is the value passed on form submit, and title is the option text shown to the user. For example: | Field 9 | select+values | 3 | One, 2: Two, III: Three | Various values formats | shows OneTwoThree but the values of options Two and Three are 2 and III, respectively. A legacy title=value syntax is supported as well, for example: One, Two=2, Three=III.
select+multi+values	Combination of select+multi and select+values
color	Single-line text box and a color picker to pick a color. The color can also be typed into the text box, such as #123456. An attribute of type="popup" shows a button that, when clicked, opens a color picker popup.	Text box width in number of characters	Initial (default) color
date	Text input field and a button next to it to pick a date from a pop-up calendar. The date can also be typed into the text box.	Text box width in number of characters	Initial (default) date

Note on Attributes:

• Common attributes: hidden, mandatory, class, form, onblur, onfocus, onchange, onselect, onmouseover, onmouseout, spellcheck, style, tabindex, title, translate
• Type-specific attributes:
  • text type: id, max, maxlength, min, pattern, placeholder
  • textarea type: autocomplete, id, maxlength, minlength, pattern, placeholder, wrap
  • label type: id, max, maxlength, min
  • combobox type: max, maxlength, min, pattern, placeholder

Values in Other Topics

As described above, you can also retrieve possible values for select, checkbox or radio types from other topics. For example, if you have a rows defined like this:

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

Using a form template on a different web

You can use a form template on a different web by specifying a form template in the WEB.TOPIC format.

In addition, you can put a comma separated list of webs in the TWIKIFORMPATH variable. It's referred to only when a form template is spcified without a web (TOPIC instead of WEB.TOPIC). The webs in TWIKIFORMPATH are examined in the listed order until the specified template is found.

TWIKIFORMPATH may contain TWiki variables. For example:

   * Set TWIKIFORMPATH = %APPLICATION_WEB%, %WEB%

If TWIKIFORMPATH is defined, the current web is examined only if all the webs listed in it don't have the form template.

Extending the range of form data types

You can extend the range of data types accepted by forms by using TWikiPlugins. All such extended data types are single-valued (can only have one value) with the following exceptions:

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

Hints and Tips

Editing Just Form Data, Without Topic Text

In some cases you want to change only the form data. You have the option of hiding the topic text with two methods:

• To display only the form whenever you edit a topic, set the preference variable EDITACTION to value form (see details).
• To change the edit action in a URL, add a action=form parameter to the edit URL string, such as
  %SCRIPTURL{edit}%/%BASEWEB%/%BASETOPIC%?t=%SERVERTIME{$epoch}%;action=form (see details).

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.

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.

Update Specific Form Fields

All the form fields are shown and can be updated when editing a topic that has a form. It is possible to have more control over the layout of a form, or update just a subset of the form fields by using a custom HTML form. For example, in a bug tracker, each topic would include a header topic that shows a form with some fields to update specific form fields of the bug item. Use the EDITFORMFIELD variable to easily create this form in the header topic. Example:

%EDITFORMFIELD{ "form" type="start" action="save" topic="%BASETOPIC%" }%
| Priority: | %EDITFORMFIELD{ "Priority" topic="%BASETOPIC%" }% |
| Status:   | %EDITFORMFIELD{ "Status"   topic="%BASETOPIC%" }% |
|  | %EDITFORMFIELD{ "form" type="submit" value="Update" }% |
%EDITFORMFIELD{ "LastUpdate" type="hidden" value="%SERVERTIME{$year-$mo-$day}%" }%
%EDITFORMFIELD{ "form" type="end" }%

Assuming the base topic has a BugForm with Priority and Status fields of type select, a LastUpdate field of type text, and some other fields. Above form shows a table with selectors for Priority and Status, and an Update button. On form submit, the Priority, Status and LastUpdate fields are updated in the base topic.

Searching for Form Data

TWiki Forms accept user-input data, stored as TWikiMetaData. Meta data also contains program-generated info about changes, attachments, etc. To find, format and display form and other meta data, see TWikiMetaData, EDITFORMFIELD, FORMFIELD, SEARCH and METASEARCH variables in TWikiVariables, and TWiki Formatted Search.

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" sort="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.

Managing Topics

Browser-based rename, move, and delete for individual topics

Overview

You can use browser-based controls to change a topic's name, move it to another TWiki web, or delete it to a hidden Trash web.

How to Rename/Move/Delete a Topic

1. Click on [More topic actions] (bottom right of page) on the topic to be changed, then, in the new screen, on [Delete topic] or [Rename/move topic]. You can now rename and/or move/delete in one operation:
2. To web: Select the target web if other than the current web.
3. To topic: Enter the new topic name - default is current name
   NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.
4. Update links: Prevent updates by unchecking individual items on the list of referring links - these topics will NOT to be updated with the new name (by default, all referring links will be updated).
5. Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.
   • If any of the referring pages are locked then they will be listed: you can correct these later by again pressing [Rename/Move].
   • There is a Put back feature that allows you to undo a Rename/Move/Delete - an instruction line and undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.

Deleted Topics: How to Clear the Trash

Deleted topics are moved to a special Trash web - they are NOT physically erased from the server. All webs share Trash - in case of a name conflict with a topic already Trash, the user is alerted and asked to choose a new name.

The Trash web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the Trash directory.

• This can only be done from on the server, not through the browser.
  • Since simple FTP access to the Trash directory is all that's required for maintenance, it's possible to grant Trash admin privileges to multiple users, while strictly limiting server access.

Redirecting from an Old Topic

You can use TWikiMetaData to place a command in the WebTopicViewTemplate and WebTopicNonWikiTemplate that will indicate that a topic has been moved by searching for %META:TOPICMOVED{...}%. Customize something like this:

%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" 
title="This topic used to exist and was moved to: "}%

Note: Do not modify the TWiki.WebTopicViewTemplate - modifications would be lost on the next TWiki upgrade. Instead, create a WebTopicViewTemplate in the Main web with the same content and modify it to your needs.

How Rename/Move Works

1. %SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.
   • User can omit one or more topics from the update list by unchecking them.
   • <pre> and <verbatim> are honored - no changes are made to text within these areas.
2. The topic is moved (if locks allow).
3. References are changed (locks and permissions permitting).
4. Any referring topics that can't be changed due to locks are listed - user can take note and change them at another time.

How Referring Topics Are Found

First, matching topics in the current web are listed - matches are to topic. Next, all webs (including the current one) are listed that match web.topic. All webs will be searched during rename, even if NOSEARCHALL is defined on a web, though access permissions will of course be honored.

Changed references are kept are as short as possible, ex: topic is used in preference to web.topic.

Effect of User Access Settings

User permissions affect the 'rename' functions in various ways. To rename a topic, you need all of VIEW, CHANGE and RENAME access to that topic. To alter referring topics, you need CHANGE access. See TWikiAccessControl for information on setting up access permissions.

Special Considerations

Consider carefully whether to make browser-based Rename/Move/Delete widely available, or to restrict it to an administrator/moderator group. Allowing all users to easily manipulate topics can be extremely useful in refactoring a busy web or site. However, there are at least two significant potential drawbacks to take into account:

• When referring links are updated, the modified topics appear in WebChanges, creating the impression that editorial changes were made. This can undermine the usefulness of WebChanges.
• Due to current limitations, fairly heavy use of Rename/Move/Delete functions can lead to an accumulation of minor technical problems (ex: broken links) and usability issues (ex: user confusion). If Rename... is used heavily, these negatives will obviously increase, in number and effect.

Ultimately, the size, objectives, and policies of your TWiki site, the real-world behavior of your user group, and most importantly, the initial TWiki site management leadership, will determine the most effective implementation of this feature, and the success of the site overall.

Known Issues

Rename/Move is fairly complicated due to the dynamic generation of links. Ideally, it would be possible to run the required part of rendering in a way that would allow identification of the text to be changed. Unfortunately, these hooks don't exist in TWiki at present. Instead, %SEARCH% is used with a special template to show the text to be changed, and the selected topics are then altered. One drawback is that search can show matches that will not be updated due to case differences. Other mismatches with actual rendered output are also possible as the approaches are so different.

The following shows some limitations of square bracket processing.

[[Old Topic]]  => [[NewTopic][Old Topic]]
[[old topic]]  => [[NewTopic][old topic]]
[[old t opic]] => not changed
[[OldTopic]]   => [[NewTopic]]

Related Topics: UserDocumentationCategory, AdminDocumentationCategory