These topics are for frequently
asked questions including answers.
* Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
* Set THEFIELD = TopicClassification

These topics are for frequently
asked questions including answers.
* Set THETOPIC = System.FAQWhatIsWikiWiki
* Set THEFIELD = TopicClassification

Delayed form

Standard form macros can nearly always be used to build the parameter string of another macro; however, sometimes it is desirable to bypass the inside-out expansion order and delay the inner macro until after the outer macro has finished expansion. This is accomplished by using the $percent format token instead of %, and escaping any " character it uses (becomes \")

When working with a given macro, consult its documentation to determine which parameters support the $percent/$percntformat tokens. Generally only output parameters like header, format and footer support format tokens.

Macro Names

Macro names must start with a letter. The following characters can be letters, numbers and the underscore '_'. Letters may be upper or lower-case, E.g. %MYVAR%, %MyVar%, %My2ndVar%, and %My_Var% are all separate, valid macro names (macros are case sensitive - %MyVAR% and %MYVAR% are not the same).

By convention all settings, predefined macros and macros registered by plugins are always UPPER-CASE.

Help on Preferences

A preference setting lets you define a simple macro that can be expanded in your output. Preference settings do not accept any parameters.

A preference setting looks like this: 3 or 6 spaces * Set NAME = value Example:

* Set WEBBGCOLOR = #FFFFC0

A preferences setting can be disabled with a # sign. Remove the # sign to enable a local customisation. Example:

* #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser

Macros defined using preference settings are expanded by enclosing the name in percent signs. Example:

When you write %WEBBGCOLOR%, it gets expanded to #FFD8AA

You can introduce your own preference settings and use them in your topics and templates.

A preference settings is always taken from the most current topic revision, even when accessing previous revisions of a topic.

Set statements which occur at higher-numbered locations override settings of the same name at lower numbered levels, unless the macro was listed in a FINALPREFERENCES setting (finalised) at a lower-numbered level. In this case, the macro is locked to the value at that level; Set statements at higher-numbered levels are ignored.

If you are setting a preference and using it in the same topic, note that Foswiki reads all the preference settings from the saved version of the topic before it displays anything. This means you can use a macro 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 macro you are using in the same topic, Preview will show the wrong thing, and you must Save the topic to see it correctly.

Also note that Foswiki always reads the setting from the most current topic revision, so viewing older revisions of a topic can show unexpected results.

The syntax for setting macros is the same anywhere: [multiple of 3 spaces] * [space] Set [space] MACRONAME [space] = [space] value

Examples:

* Set MACRONAME = value
* Set MACRONAME = 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 MACRONAME = value starts here
and continues here

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

You can also set preference settings in a topic by clicking the link Edit topic preference settings under More topic actions. Preferences set in this manner are known as 'meta' preferences and are not visible in the topic text, but take effect nevertheless.

Access Control Settings

These are special types of preference settings to control access to content. AccessControl explains these security settings in detail.

Local values for preferences

Certain topics (user, plugin, web, site and default preferences topics) have a problem; macros 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 macro definition. For example, if the user sets the following in their home topic:

* Set EDITBOXHEIGHT = 10
* Local EDITBOXHEIGHT = 20

Then, when they are editing any other topic, they will get a 10 high edit box. However, when they are editing their home topic they will get a 20 high edit box.
Local can be used wherever a preference needs to take a different value depending on where the current operation is being performed.

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

Predefined Macros

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

Plugins may extend the set of predefined macros (see individual Plugins topics for details)

Take the time to thoroughly read through ALL preference macros. If you actively configure your site, review macros periodically. They cover a wide range of functions, and it can be easy to miss the one perfect macro for something you have in mind. For example, see %BASETOPIC%, %INCLUDE%, and the mighty %SEARCH%.

ADDTOHEAD

This macro is deprecated. Please use VarADDTOZONE instead.
It effecively is a shortcut for %ADDTOZONE{"head" ...}%

ADDTOZONE

%ADDTOZONE{
"zone"
...
}%

Parameters:

"zone" optional, comma-separated list of the names of zones that the content should be added to. The only zones guaranteed to exist are head and script. Defaults to head.

id optional, identifier for the text being added with the ADDTOZONE call, to be used in the requires parameter of other ADDTOZONE calls.

Multiple ADDTOZONE calls with the same id parameter will simply overwrite the earlier ADDTOZONE call.

requires="..." optional, comma separated string of ids of text within this zone that this content should follow when the zone is rendered.

text="..." optional, text to be added to the named zone, mutually exclusive with topic.

topic="..." optional, full qualified web.topic name that contains the text to be added, mutually exclusive with text. Defaults to %BASETOPIC%

section="..." optional, section of the topic to be added, defaults to the default section between STARTINCLUDE and STOPINCLUDE.

What is a "Zone"?

Zones are specific places in the output HTML that are marked by calls to the
RENDERZONE macro. Zones are used to collect various content
together, such as Javascript and CSS, that must be included in the output HTML
in a specific order, and in a specific place.

There are two special zones called head and script. The head zone is rendered
as part of the HTML head section. It is the catch-all container for any content supposed
to be placed into the HTML head section, except Javascript, which is collected in the
script zone.

All Javascript must always be added to the script zone exclusively, in order to
grant ordering constraints among scripts are resolved properly. Never add Javascript to
the head zone -- never add non-Javascript content to the script zone.

Both zones are added to the HTML head section automatically just before the
closing </head> tag as if they were specified explicitly in the skin templates using:

<head>
...
%RENDERZONE{"head"}%
%RENDERZONE{"script"}%
</head>

You may create as many zones in addition to the standard head and script
zones as you like. For any non-standard zone specified in
ADDTOZONE you will also need to provide an appropriate
RENDERZONE.

Interesting use cases in wiki applications:

Create a sidebar zone to add widgets,

Create a toolbar zone to add buttons icons

Create a menu zone to add menu entries

Adding content to a zone

ADDTOZONE adds content to a zone identified with the id parameter.
An id identifier is unique within the zone that they are added to.
When the same id is used in multiple calls to ADDTOZONE the
last call will win, that is previous content of the same id will be overwritten.

Enforcing a linear order of content within a zone

An ADDTOZONE call may ensure that its content appears after the
content of some other ADDTOZONE calls by specifying their ids in
the requires parameter. The requires parameter constraints the linear order
of content added to a zone. When a zone is rendered, all ordering constraints
expressed via requires are satisfied. Those ids not found in a zone don't
have any influence on the final ordering. Missing ids aren't considered an error
rather than an over-specified ordering problem.

Working with {MergeHeadAndScriptZones} disabled (default)

In this mode, the head and script zones are treated separately.

Even when head and script zones are treated separately, the head zone will
always be rendered before the script zone, unless otherwise specified using RENDERZONE explicitly.
So any content in the script zone that depends on content placed into
the head zone is satisfied intrinsicly as they are both rendered as specified above.

Working with {MergeHeadAndScriptZones} enabled

In this mode, the head and script zones are separate when adding to them,
but may be treated as merged when you call RENDERZONE if
there are any dependencies specified that only exist in the opposite zone. This
allows an ADDTOZONE{"head"...} to to successfully require an id that has
been added to script.

{MergeHeadAndScriptZones} is provided to
maintain compatibility with legacy extensions that use
ADDTOHEAD to add <script> markup and require content
that is now in the script zone. {MergeHeadAndScriptZones} will be removed
from a future version of Foswiki.

Example: Adding to a zone with missing dependencies

You must ensure that no head content (and no inline Javascript) depends on
script content. Any such dependency will be ignored.

In real world application this isn't a problem as Javascript is never added
to the head zone or Javascript zone part of the script zone never really
depends on non-Javascript content part of the head zone.

HTML comment decoration which normally appears after each id's
content in the rendered HTML will contain a small informative text to aid
debugging.

Example: Adding Javascript to a page

Make sure that all inline Javascript code in the topic (if it is allowed)
is added to the page using %ADDTOZONE{"script"...requires="library-id"}%
with the appropriate library-id to guarantee a correct load order. For example, jQuery code should be added as follows:

The %CALC{"formula"}% macro is handled by the SpreadSheetPlugin. There are around 90 formulae, such as $ABS(), $EXACT(), $EXISTS(), $GET()/$SET(), $IF(), $LOG(), $LOWER(), $PERCENTILE(), $TIME(), $VALUE().

Syntax: %CALC{"formula"}%

Examples:

%CALC{"$SUM($ABOVE())"}% returns the sum of all cells above the current cell

This is the name of the template to use for this comment. Comment templates are defined in a Foswiki template - see Customisation, below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your WebPreferences.

EDITACTION -- Selects an edit template

The EDITACTIONpreference setting lets you define the use of an editaction template instead of the standard edit. If EDITACTION is defined as text, then hide the form. If EDITACTION is defined as form hide the normal text area and only edit the form.

Syntax:

* Set EDITACTION = text|form

Expands to: %EDITACTION%

When EDITACTION is defined as text or form the Edit and Edit Raw buttons simply add ;action=text or ;action=form to the URL for the edit script. If you have defined an EDITACTIONpreference setting you can still edit the topic content or the form by removing the ;action=form or ;action=text from the edit URL in the browser and reload.

Rows can be added and removed if "on" Rows can be added but not removed if "add" Rows cannot be added or removed if "off"

CHANGEROWS plugin setting

quietsave

Quiet Save button is shown if "on", hidden if "off"

QUIETSAVE plugin setting

include

Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. Use topic or web.topic notation.

(none)

helptopic

Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% macros can be used in the topic to specify what is shown.

(no help text)

headerislabel

Table header cells are read-only (labels) if "on"; header cells can be edited if "off" or "0"

"on"

editbutton

Set edit button text, e.g. "Edit this table"; set button image with alt text, e.g. "Edit table, %PUBURL%/%SYSTEMWEB%/DocumentGraphics/edittopic.gif"; hide edit button at the end of the table with "hide" (Note: Button is automatically hidden if an edit button is present in a cell)

EDITBUTTON plugin setting

buttonrow

Set to top to put the edit buttons above the table.

bottom

javascriptinterface

Use javascript to directly move and delete row without page refresh. Enable with "on", disable with "off".

ENCODE{"string"} -- encodes a string

Encode character sequences in "string", by mapping characters (or sequences of characters) to an alternative character (or sequence of characters). This macro can be used to encode strings for use in URLs, to encode to HTML entities, to protect quotes, and for as many other uses as you can imagine.

Comma-separated list of tokens to replace. Tokens are normally single characters, but can also be sequences of characters. The standard format tokens may be used in this list. Each token must be unique - you cannot list the same token twice.

May not be used with type; required if new is used

new="tokenlist"

comma-separated list of replacement tokens. The elements in this list match 1:1 with the elements in the old list. Again, the standard format tokens may be used. An empty element in the new list will result in the corresponding token in the old list being deleted from the string. If the new list is shorter than the old list it will be extended to the same length using the empty element. Tokens do not have to be unique.

When using old and new, be aware that the results of applying earlier tokens are not processed again using later tokens. (see examples below)

May not be used with type; required if old is used

If ENCODE is called with no optional parameters (e.g. %ENCODE{"string"}%) then the default type="url" encoding will be used.

ENCODE can be used to filter user input from URL parameters and similar to help protect against cross-site scripting. The safest approach is to use type="entity". This can however prevent an application from fully working. You can alternatively use type="safe" which encodes only the characters '"<>% into HTML entities. When ENCODE is passing a string inside another macro always use double quotes ("") type="quote". For maximum protection against cross-site scripting you are advised to install the Foswiki:Extensions.SafeWikiPlugin.

Double quotes in strings must be escaped when passed into other macros. Example:

If the STARTSECTION is named, the corresponding ENDSECTION must also be named with the same name. If the STARTSECTION specifies a type, then the corresponding ENDSECTION must also specify the same type. If the section is unnamed, ENDSECTION will match with the nearest unnamed %STARTSECTION%of the same type above it.

ENV{"varname"} -- inspect the value of an environment variable

Returns the current value of the environment variable in the CGI (Common Gateway Interface) environment. This is the environment that the CommandAndCGIScripts are running in.

Note: For security reasons, only those environment variables whose names match the regular expression in {AccessibleENV} in the Security Settings/Miscellaneous section of configure can be displayed. Any other variable will just be shown as an empty string, irrespective of its real value.

Example: %ENV{MOD_PERL}% displays as: not set

If an environment variable is undefined (as against being set to the empty string) it will be returned as not set.

EXPAND{"expression" scope="topictoexpandin" ...}%

Expands macros in expression as if they were used in the topic topictoexpandin. The viewer must have VIEW access to topictoexpandin for this to work. All the standard formatting macros can be used in expression, such as $percent and $quot.

EXPAND can be useful when you want to pick up the value of macros defined in another topic. For example, you might want to define a set of preferences in one topic, but pick up their value in another topic (this is very useful when building reusable applications). In this case you can write:

* Set MYPREFERENCE = value

in "SettingsTopic" and then, in "MyTopic", write:

%EXPAND{"$percentMYPREFERENCE$percent" scope="SettingsTopic"}%

Of course we can also write:

%EXPAND{"$percentMYPREFERENCE$percent" scope="%OTHERTOPIC%"}%

which lets us select which other topic to get the preference value from.

Additional parameters can be passed to the macro being expanded using the standard macro syntax in the name of the macro; for example,

If type="string" then the comma separated list is treated as a list of
strings. In this case, the format tokens $index and $item will return
the position of the item in the list (1-based), and the item itself,
respectively. Note that a comma can be embedded in the data using the standard
formatting token $comma.

The FORMAT macro is currently only of use in formatting lists of topics,
or of simple strings. It will be extended in future releases to add the
capability to render other object types.

For more sophisticated handling of string lists, consider installing
Foswiki:Extensions.FilterPlugin.

Format string. $value expands to the field value, and $name expands to the field name, $title to the field title, $form to the name of the form the field is in. The standard format tokens are also expanded.

"$value"

default="..."

Text shown if the field is defined in the topic, but the field value is empty. For example, a text field for which all the content has been deleted.

""

alttext="..."

Text shown if the field is not defined in the topic (even if it is specified in the form definition). For example, this is used when a field exists in the form definition, but the referring topic hasn't been edited since it was added.

""

rev="n"

Specifiy a revision of the topic. If not specified, defaults to the most recent rev (or the viewed rev if viewing an old rev of the same topic)

Example:

%FORMFIELD{"ProjectName"
topic="Projects.SushiProject"
default="(no project name given)"
alttext="ProjectName field not found in form"
}%

If set, and there are no Groups or Members that can be shown, the header and footer are suppressed, and this text is output

undefined

show

filter the output list of Groups - can be set to all, allowschange, denychange, allowschange(UserWikiName), denychange(UserWikiName)

all

expand

Set false if users should not be expanded from nested groups. Default behavior is to expand all nested groups into a flat list of users.

1

limit

If set, limits the number of results to this

infinity

limited

If limit is set, and the list is truncated, this text will be added at the end of the list

''

Note: GROUPINFO will not list members that are hidden from the current authenticated user. If the current user does not have VIEW authority for a user's topic, then the user will not be shown as a group member.

Format of one line, may include any variable which is supported by macro REVINFO

"r$rev - $date - $wikiusername"

topic="topic"

Topic name, can be in web.topic format

current topic

web="web"

Web name

current web

versions="number or range"

Number or range (format: from..to). Examples: To get version 2, write: versions="2" To get version 2 to 3, write: versions="2..3" To get version 2 to the latest, write: versions="2.." To get all versions up to version 5, write: versions="..5" To get all versions up to but not including the latest, write: versions="..-1" To get the versions from 1 to 5 in reverse order, write: versions="5..1"

all versions in the order latest to first

header="text"

Text to print before the list. May contain the tokens $next and $previous which will be evaluated if there are newer or older revisions available for the topic that are not listed according to versions (or rev1, rev2, nrev). These tokens take the syntax $next{'some text' url='url'} (the same for $previous). 'some text' is the text which should be printed, 'url' is the url for the corresponding link. The tokens $rev1, $rev2, $nrev in 'text' or 'url' will be replaced by appropriate values for the next or previous block of revisions. See the attached oopshistory.tmpl for an example of how to use this.

"$next"

footer="text"

Text to print after the list. May contain the tokens $next and $previous (see header)

"$previous"

Deprecated (but supported) parameters:

Argument

Description

Default value

nrev="number"

Number of revisions to show. Ignored if versions is specified, or if both rev1 and rev2 are specified.

10

rev2="number"

Newest revision to show

rev1+nrev if rev1 is specified, latest revision otherwise

rev1="number"

Oldest revision to show

rev2-nrev

reverse="boolean"

Show newest revisions first, if on

"on"

Additional macros

The following macros are replaced only if there is a corresponding %HISTORY% on the page. If more than one %HISTORY% is used on the same page, the values from the last one will be used.

I -- idea icon

ICON{"name" alt="" default="name"} -- small documentation graphic or icon of common attachment types

Generates a small graphic image from the set attached to DocumentGraphics. Images typically have a 16x16 pixel size. You can select a specific image by name, or you can give a full filename, in which case the type of the file will be used to select one of a collection of common file type icons.

if you specify an icon which cannot be found, the one specified in the default parameter will be used (and if that fails, the 'else' icon will be used)

ICONURL{"name" default="name"} -- URL of small documentation graphic or icon

Generates the full URL of a DocumentGraphics image, which Foswiki renders as an image. The related %ICON{"name"}% generates the full HTML img tag. Specify image name or full filename (see ICON for details on filenames.)

Includes only the specified named section, as defined in the included topic by the STARTSECTION and ENDSECTION macros. Nothing is shown if the named section does not exists. section="" is equivalent to not specifying a section

PARONE="val 1" PARTWO="val 2"

Any other parameter will be defined as a macro within the scope of the included topic. The example parameters on the left will result in %PARONE% and %PARTWO% being defined within the included topic.

When a page is included, normally Biofuels Wiki will process it, doing the following: 1) Alter relative links to point back to originating host, 2) Remove some basic HTML tags (html, head, body, script) and finally 3) Remove newlines from HTML tags spanning multiple lines. If you prefer to include exactly what is in the source of the originating page set this to on. raw="on" is short for disableremoveheaders="on", disableremovescript="on", disableremovebody="on", disablecompresstags="on" and disablerewriteurls="on".

disabled

literal="on"

While using the raw option will indeed include the raw content, the included content will still be processed and rendered like regular topic content. To disable parsing of the included content, set the literal option to "on".

disabled

disableremoveheaders="on"

Bypass stripping headers from included HTML (everything until first </head> tag)

disabled

disableremovescript="on"

Bypass stripping all <script> tags from included HTML

disabled

disableremovebody="on"

Bypass stripping the </body> tag and everything around over and below it

JQREQUIRE{"plugin, plugin, ... "} -- enable a plugin on the current page

This macro will load a list of plugins to be added to the current page. Use JQPLUGINS to display the list of available and active plugins. While loading a plugin, additional plugins it may depend on are loaded as well. Information about these dependencies is stored within the plugins themselves and can't be changed. Dependencies also make sure the javascript code is added to the html page in the right order. It uses ADDTOZONE to aggregate javascript and css at the right place on the html page.

JQTHEME{"name" ...} -- switch jQuery UI theme

Foswiki's default UI theme is configured in $Foswiki::cfg{JQueryPlugin}{JQueryTheme} and defaults to base. Use configure to change this site wide. Use JQTHEME if you decide to use a different theme on the current page.

Note: some Foswiki skins may come with their own jQuery UI matching the overall user experience of the web design.

Example: <select>%LANGUAGES{format="<option $marker value='$langtag'>$langname</option>" selection="%LANGUAGE%"}%</select> creates an option list of the available languages with the current language selected

An ampersand (&) followed by one ascii alphabetic character (a...z, A...Z) in the translatable string will be expanded to an access key string. For example, &X will expand to <span class='foswikiAccessKey'>X</span>. If you want to write an actual ampersand, either follow it with a non-alphabetic character or write two consecutive ampersands (&&).

Translatable strings starting with underscores (_) are reserved. You cannot use translatable phrases starting with an underscore.

Make sure that the translatable string is constant. Do not include %MACROS% inside the translatable strings as they will be expanded before the %MAKETEXT{...}% itself is handled. You can, however, use macros in the args, as shown in the examples above.

The string will be output in English if no mapping can be found in the .po translation file for the current user's selected language.

What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children "field" if searching for topics that have a particular form field value (use the name and value parameters to specify which field to search).

Required

web="%WEB%"

Wiki web to search: A web, a list of webs separated by whitespace, or all webs.

Current web

topic="%TOPIC%"

The topic the search relates to, for topicmoved and parent searches

All topics in a web

name

form field to search, for field type searches. May be a regular expression (see SEARCH).

value

form field value, for field type searches. May be a regular expression (see SEARCH).

rev="version" - operate on the given version of the current topic. Note that this will only affect simple queries that refer to the current topic, such as form.name. More complex queries that use searches or indirection to refer to other topics always use the latest version of those topics.

Examples:

Get the name of the form in the current topic:
%QUERY{"form.name"}%
Get the value of the 'Firstname' form field in
the current topic:
%QUERY{"fields[name='Firstname'].value"}%
Get the value of the 'Firstname' form field in
the current topic (shorthand version):
%QUERY{"Firstname"}%
Get a list of all the names of attachments on
the topic 'System.DocumentGraphics':
%QUERY{"'System.DocumentGraphics'/attachments.name"}%
Get configuration setting {NameFilter}:
%QUERY{"{NameFilter}"}%

Plain strings (such as field values) are returned without quotes. Simple arrays of scalars are also returned without quotes, in a comma-separated list (beware of values that contain commas!).

More complex data structures (e.g. arrays of hashes) will be returned as Perl code strings generated by running through CPAN:Data::Dumper.

You can make the macro generate different output formats using the style parameter:

Control how special characters are encoded. If this parameter is not given, "safe" encoding is performed which HTML entity encodes the characters '"<>%. entity: Encode special characters into HTML entities, like a double quote into &#034;. Does not encode \n or \r. safe: Encode characters '"<>% into HTML entities. (this is the default) html: As type="entity" except it also encodes \n and \rquotes: Escape double quotes with backslashes (\"), does not change other characters url: Encode special characters for URL parameter use, like a double quote into %22

String value of the parameter. Multi-valued parameters will have a "row" for each value.

$n or $n()

New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar

Most macros accept parameter strings which are split over multiple lines. This is usually more readable than using $n tokens. If you are familiar with sectional includes, you might also consider nested sectional includes to hold the newline content outside of the parameter string entirely.

$nop or $nop()

Is a "no operation". This token gets removed; useful for nested search

Using QUERYPARAMS can easily be misused for cross-site scripting unless specific characters are entity encoded. By default QUERYPARAMS encodes the characters '"<>% into HTML entities (same as encoding="safe") which is relatively safe. The safest is to use encoding="entity". When passing QUERYPARAMS inside another macro always use double quotes ("") combined with using QUERYPARAMS with encoding="quote". For maximum security against cross-site scripting you are adviced to install the Foswiki:Extensions.SafeWikiPlugin.

QUERYSTRING -- full, unprocessed string of parameters to this URL

String of all the URL parameters that were on the URL used to get to the current page. For example, if you add ?name=Samantha;age=24;eyes=blue to this URL you can see this in action. This string can be appended to a URL to pass parameter values on to another page.

URLs built this way are typically restricted in length, typically to 2048 characters. If you need more space than this, you will need to use an HTML form and =%QUERYPARAMS%=

header and footer are not output if there is no content in the zone (nothing has been ADDTOZONEd ). However they are output if the output is the empty string (at least one ADDTOZONE has been processed).

Zones are cleared after being rendered; they are only ever rendered once.

head and script are automatic zones. They don't require a corresponding RENDERZONE anywhere in the templates - they are automatically inserted before the </head> tag in the output HTML page.

Normally, dependencies between individual ADDTOZONE statements are resolved within each zone. However, if {MergeHeadAndScriptZones} is enabled in configure, then head content which requires an id that only exists in script will be re-ordered to satisfy this dependency.

{MergeHeadAndScriptZones} will be removed from a future version of Foswiki.

SEARCH{"text"} -- search content

Search term. Is a keyword search, literal search, regular expression search, or query, depending on the type parameter. SearchHelp has more

required

search="text"

(Alternative to above)

N/A

web="Name"web="Main, Know"web="all"

Comma-separated list of webs to search. You can specifically exclude webs from an all search using a minus sign - for example, web="all,-Secretweb". The special word all means all webs that do not have the NOSEARCHALL preference set to on in their WebPreferences. Note that AccessControls are respected when searching webs; it is much better to use them than NOSEARCHALL. Wildcards are not currently supported for web names.

Current web

topic="WebPreferences"topic="*Bug"

Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names.

All topics in a web

excludetopic="Web*"excludetopic="WebHome, WebChanges"

Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names.

None

scope="topic"scope="text"scope="all"

Search topic name (title); the text (body) of topic; or all (title and body)

"text"

type="keyword"type="word"type="literal"type="regex"type="query"

Control how the search is performed when scope="text" or scope="all"keyword: use Google-like controls as in soap "web service" -shampoo; searches word parts: using the example, topics with "soapsuds" will be found as well, but topics with "shampoos" will be excluded word: identical to keyword but searches whole words: topics with "soapsuds" will not be found, and topics with "shampoos" will not be excluded literal: search for the exact string, like web serviceregex: use a RegularExpression search like soap;web service;!shampoo; to search on whole words use \bsoap\bquery: query search of form fields and other meta-data, like (Firstname='Emma' OR Firstname='John') AND Lastname='Peel'

Sort the results of search by the topic names, topic creation time, last modified time, last editor's WikiName, or named field of DataForms. The sorting is done web by web; if you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort. Note that dates are sorted most recent date last (i.e at the bottom of the table).

Sort by topic name

limit="all"limit="16"

Limit the number of topics from which results will be returned. This is done after sorting if order is specified. Note that this does not limit the number of hits from the same topic when you have multiple="on".

All results

date="..."

limits the results to those pages with latest edit time in the given time interval.

All results

reverse="on"

Reverse the direction of the search

Ascending search

casesensitive="on"

Case sensitive search

Ignore case

bookview="on"

BookView search, e.g. show complete topic text. Very resource demanding. Use only with small result sets

Show default search header, unless search is inline and a format is specified (Cairo compatibility)

nototal="on"

Do not show number of topics found

Show number

zeroresults="off" or zeroresults="..."

Suppress/replace all output if there are no hits (the boolean nature of the setting uses true, false, on, off, 0 so those cannot be used as a format string on their own (insert a to escape them))- can also be set to a FormattedSearch string to customise the output

zeroresults="on" - displays the summary, and number of topics found. "Number of topics: 0"

Expand embedded macros 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

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

nofinalnewline="on"

If on, the search variable does not end in a line by itself. Any text continuing immediately after the SEARCH macro on the same line will be rendered as part of the table generated by the search, if appropriate. This feature is only active when format is defined.

on

recurse="on"

Recurse into subwebs, if subwebs are enabled. Note: recurse will currently search subwebs of explicitly excluded webs. (web="all, -Sandbox" recurse="on") will still search subwebs of Sandbox. This behavior is likely to change in a future release.

off

separator=", "

Line separator between search hits (only used when format= is set) uses FormatTokens. If separator is not defined, the default is "$n" (newline). Not defining the separator will additionally cause a newline to be added after a header and before a footer.

"$n" (Newline)

newline="%BR%"

Line separator within a search hit. Useful if you want to put multi-line content into a table cell, for example if the format="" parameter contains a $pattern() that captures more than one line.

"$n" (Newline)

pagesize="25"

number of items to show per page

"25"

showpage="1"

Page of items to show (starts at 1) (over-ridden by the value specified by the URL parameter hash from $previousurl and $nexturl)

"1"

pager="on"

appends the pager to the footer format (the quickest way to add paging to your SEARCHes is to just add pager="on") Note: the default pager (when pagerformat is not defined) requires the parameters to the SEARCH to not change while paging, as it uses $previousurl and $nexturl which use a hash of the Macro's parameters to override the value of showpage. If you use time variable parameters, you will need to define your own pagerformat.

Warning: this option is liable to change dramatically (and potentially incompatibly) in the next major release of foswiki. Setting to "none" applies only to multi-web SEARCHs, and means the header and footer are only output once - at the beginning and end of the list of results, and the order parameter is applied over the entire set of results (this setting removes the legacy that results are always partitioned by web) see SiteChanges for an example.

STARTINCLUDE -- start position of topic text if included

If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% macro. A normal view of the topic shows everything exept the %STARTINCLUDE% macro itself.

Syntax: %STARTINCLUDE%

If you want more than one part of the topic included, use %STARTSECTION{type="include"}% instead

STARTSECTION -- marks the start of a section within a topic

Section boundaries are defined with %STARTSECTION{}% and %ENDSECTION{}%.

Sections may be given a name to help identify them, and/or a type, which changes how they are used.

type="section" - the default, used for a generic section, such as a named section used by INCLUDE.

type="include" - like %STARTINCLUDE% ... %STOPINCLUDE% except that you can have as many include blocks as you want which are all merged into one when included (%STARTINCLUDE% is restricted to only one). Sections of type include may not be given a name.

type="expandvariables" - all macros inside an "expandvariables" type section gets expanded when a new topic based on the template topic is created. See TemplateTopics for more information.

type="templateonly" - start position of text to be removed when a template topic is used. This is used to embed text that you do not want expanded when a new topic based on the template topic is created. See TemplateTopics for more information.

Type of the section; type "section", "expandvariables", "include" or "templateonly"

"section"

If a section is not given a name, it will be assigned one. Unnamed sections are assigned names starting with _SECTION0 for the first unnamed section in the topic, _SECTION1 for the second, etc..

You can define nested sections. It is not recommended to overlap sections, although it is valid in Foswiki. Use named sections to make sure that the correct START and ENDs are matched. Section markers are not displayed when a topic is viewed.

TAB{"text" ...} -- tab inside a tabpane widget

when switching tabs, this is the javascript fragment to be executed just before the tab is displayed

after

this javascript handler is to be executed after the tab has been made visible

afterload

this javascript handler will be called when content loaded asynchronously (using the url parameter, below) has finished loading; depending on the network latency, this can be significantly later than execution of the after handler above

id

id of this tab; this id can be used in the TABPANEs select parameter to display this tab; this id is also added to the class attribute of the html element representing the tab button

url

link from where to load the content of the tab asynchronously when selecting this tab; the result of the addressed handler will replace the content area; if no url is set the content of the TAB ... ENDTAB area will be shown when the tab is selected

width

width of the tab area

auto

height

height of the tab area

auto

container

element where ajax content will be loaded; this is only used together with url

Attributes for tables

Table border color . Is only visible when cellspacing is larger than 1, or cellborder is 0, or tablerules is none, otherwise the cell borders overlap the table border.

unspecified

tablebordercolor="#333"

tableframe

Table frame, set to "void" (no sides), "above" (the top side only), "below" (the bottom side only), "hsides" (the top and bottom sides only), "lhs" (the left-hand side only), "rhs" (the right-hand side only), "vsides" (the right and left sides only), "box" (all four sides), "border" (all four sides).

unspecified

tableframe="hsides"

tablerules

Table rules, set to "none" (no rules), "groups" (rules will appear between row groups and column groups only), "rows" (rules will appear between rows only), "cols" (rules will appear between columns only), "all" (rules will appear between all rows and columns). See also: headerrules and datarules.

unspecified

tablerules="rows"

tablewidth

Table width: percentage of window width, or absolute pixel value.

unspecified

tablewidth="100%"

headerrows

Number of header rows to exclude from sort. (will be rendered in a HTML thead section)

"1"

headerrows="1"

footerrows

Number of footer rows to exclude from sort. (will be rendered in a HTML tfoot section)

"0"

footerrows="1"

id

Unique table identifier string, used for targeting a table with CSS.

tableN (where N is the table order number on the page)

id="userTable"

summary

Table summary used by screen readers: A summary of what the table presents. It should provide an orientation for someone who listens to the table.

unspecified

summary="List of subscribed users"

caption

Table caption: A title that will be displayed just above the table.

unspecified

caption="Users"

inlinemarkup

Set to "on" to generate inline markup HTML (in addition to the CSS markup); useful if you need to copy the table, for instance to paste the table into an email).

unspecified

inlinemarkup="on"

Attributes for table sorting

Argument

Comment

Default value

Example

sort

Set table sorting by clicking headers "on" or "off".

unspecified

sort="on"

initsort

Column to sort initially ("1" to number of columns).

unspecified

initsort="2"

initdirection

Initial sorting direction for initsort, set to "up" (descending, or decreasing in value) or "down" (ascending, or increasing in value).

down

initdirection="up"

disableallsort

Disable all sorting, both initsort and header sort. This is mainly used by plugins such as the EditTablePlugin to disable sorting in a table while editing the table.

unspecified

disableallsort="on"

Attributes for table cells

Argument

Comment

Default value

Example

cellpadding

Cell padding (pixels).

unspecified

cellpadding="0"

cellspacing

Cell spacing (pixels).

unspecified

cellspacing="3"

cellborder

Cell border width (pixels).

unspecified

cellborder="0"

valign

Vertical alignment of cells and headers, set to "top", "middle", "bottom" or "baseline".

Attributes for data cells

Argument

Comment

Default value

Example

datarules

Set to "none" (no rules), "rows" (rules will appear between rows only), "cols" (rules will appear between columns only), "all" (rules will appear between all rows and columns). Overrides tablerules for data cells.

unspecified

datarules="none"

datavalign

Vertical alignment of data cells; overrides valign.

unspecified

datavalign="top"

dataalign

Data cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to "left", "center", "right" or "justify". Overrides individual cell settings.

unspecified

dataalign="center"

databg

Data cell background colour, a comma separated list. Specify "none" for no colour, that is to use the colour/background of the page the table is on.

"#edf4f9,#fff"

databg="#f2f2f2,#fff"

databgsorted

Data cell background colour of a sorted column; see databg.

the values of databg

databgsorted="#d4e8e4, #e5f5ea"

datacolor

Data cell text colour, a comma separated list.

unspecified

datacolor="#00c, #000"

Attributes for headers

Argument

Comment

Default value

Example

headerrules

Set to "none" (no rules), "rows" (rules will appear between rows only), "cols" (rules will appear between columns only), "all" (rules will appear between all rows and columns). Overrides tablerules for header cells.

unspecified

headerrules="none"

headerbg

Header cell background colour.

"#6b7f93"

headerbg="#999"

headerbgsorted

Header cell background colour of a sorted column.

the value of headerbg

headerbgsorted="#32596c"

headercolor

Header cell text colour.

"#fff"

headercolor="#00c"

headervalign

Vertical alignment of header cells; overrides valign.

unspecified

headervalign="top"

headeralign

Header cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to "left", "center", "right" or "justify". Overrides individual cell settings.

unspecified

headeralign="left,right"

headerrows

See: Attributes for tables

Other attributes

Argument

Comment

Default value

Example

include

Other topic defining the TABLE parameters. The first %TABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. Use topic or web.topic notation.

TOC{"Topic"} -- table of contents

Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC

TOC will add an HTML anchor called foswikiTOC just before the table of contents. This enables adding a link from within a topic back to the table of contents to ease navigation. Example [[#foswikiTOC][Back to TOC]] creates Back to TOC.

If multiple headers have the exact same text, the anchors for the 2nd, 3rd etc will be suffixed by _AN1, _AN2 etc so the anchors become unique.

TOPIC -- name of current topic

%TOPIC% expands to the name of the topic. If you are looking at the text of an included topic, it is the name of the included topic.

TOPICLIST{"format"} -- topic index of a web

List of all topics in a web. The "format" defines the format of one topic item. It may include formatting tokens: The $topic token gets expanded to the topic name, $marker to marker parameter where topic matches selection, and $web to the name of the web, or any of the standard FormatTokens.

Specify if the Twisty Toggle section will use a <div> or a <span> tag. Note that if the contents contains block elements such as div, mode should be div as well to create valid HTML markup.

optional, defaults to <div>

showimgleft

Image url

Specify the url of an image that will be displayed with the show link at the left side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

hideimgleft

Image url

Specify the url of an image that will be displayed with the hide link at the left side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

showimgright

Image url

Specify the url of an image that will be displayed with the show link at the right side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

hideimgright

Image url

Specify the url of an image that will be displayed with the hide link at the right side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

remember

"on", "off"

If "on", the Twisty state is remembered the next time the page is shown. If "off", the stored setting will be cleared.

Note: when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked.

optional, no default

start

"hide" or "show"

Initial state of the Twisty; this will override any setting stored in a cookie (see remember).

optional, default no initial state

firststart

"hide" or "show"

Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see remember).

Specify if the Twisty Hide link will use a <div> or a <span> tag. Note that if the contents contains block elements such as div, mode should be div as well to create valid HTML markup.

optional, defaults to <div>

img

Image url

Specify the url of an image that will be displayed at the right side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

remember

"on", "off"

If "on", the Twisty state is remembered the next time the page is shown. If "off", the stored setting will be cleared.Note: when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked.

optional, no default

start

"hide" or "show"

Initial state of the Twisty; this will override any setting stored in a cookie (see remember).

optional, default no initial state

firststart

"hide" or "show"

Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see remember).

Specify if the Twisty Show link will use a <div> or a <span> tag. Note that if the contents contains block elements such as div, mode should be div as well to create valid HTML markup.

optional, defaults to <div>

img

Image url

Specify the url of an image that will be displayed at the right side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

imgleft

Image url

Specify the url of an image that will be displayed at the left side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

imgright

Image url

Specify the url of an image that will be displayed at the right side of the link. You may use ICONURLPATH to display one of the DocumentGraphics icons. Alternatively use an image attached to the topic.

optional, defaults to no image

remember

"on", "off"

If "on", the Twisty state is remembered the next time the page is shown. If "off", the stored setting will be cleared.Note: when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked.

optional, no default

start

"hide" or "show"

Initial state of the Twisty; this will override any setting stored in a cookie (see remember).

optional, default no initial state

firststart

"hide" or "show"

Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see remember).

Specify if the Twisty Toggle section will use a <div> or a <span> tag. Note that if the contents contains block elements such as div, mode should be div as well to create valid HTML markup.

optional, defaults to <div>

class

CSS class name

Class for content div or span

optional, default none

linkclass

CSS class name

Class for link

optional, default none

remember

"on", "off"

If "on", the Twisty state is remembered the next time the page is shown. If "off", the stored setting will be cleared.Note: when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked.

optional, no default

start

"hide" or "show"

Initial state of the Twisty; this will override any setting stored in a cookie (see remember).

optional, default no initial state

firststart

"hide" or "show"

Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see remember).

Control how special characters are encoded off: No encoding. Avoid using this when possible. See the security warning below. entity: Encode special characters into HTML entities. See ENCODE for more details. safe: Encode characters '"<>% into HTML entities. url: Encode special characters for URL parameter use, like a double quote into %22quote: Escape double quotes with backslashes (\"), does not change other characters; required when feeding URL parameters into other macros.

"safe"

multiple="on"multiple="[[$item]]"

If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" (also supports the standard format tokens)

first element

separator=", "

Separator between multiple selections. Only relevant if multiple is specified

Watch out for internal parameters, such as rev, skin, template, topic, web; they have a special meaning in Foswiki. Common parameters and view script specific parameters are documented at CommandAndCGIScripts.

If you have %URLPARAM{ in the value of a URL parameter, it will be modified to %<nop>URLPARAM{. This is to prevent an infinite loop during expansion.

Security warning! Using URLPARAM can easily be misused for cross-site scripting unless specific characters are entity encoded. By default URLPARAM encodes the characters '"<>% into HTML entities (same as encode="safe") which is relatively safe. The safest is to use encode="entity". When passing URLPARAM inside another macro always use double quotes ("") combined with using URLPARAM with encode="quote". For maximum security against cross-site scripting you are adviced to install the Foswiki:Extensions.SafeWikiPlugin.

You need to be a member of AdminGroup for the USERINFO macro to provide details about other users

The parameter should be the wikiname of a user. You can also pass a login name. You can only get information about another user if the {AntiSpam}{HideUserDetails} configuration option is not enabled, or if you are an admin. (User details are hidden in this site)

WEBLIST{"format"} -- index of all webs

List of all webs. Obfuscated webs are excluded, e.g. webs with a NOSEARCHALL = onpreference setting. The "format" defines the format of one web item. The $name gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection. Subwebs are listed recursively.

Format of one line, may include $name (the name of the web), $qname (the name of the web in double quotes), $indentedname (the name of the web with parent web names replaced by indents, for use in indented lists), and $marker (which expands to marker for the item matching selection only)

$name

format="format"

(Alternative to above)

$name

separator=", "

Line separator

$n (new line)

web=""

if you specify $web in format, it will be replaced with this value.

none

webs="public"

Comma separated list of webs to consider. This list can include two pseudo-webs, public which expands to all non-hidden and webtemplate which expands to the names of all template webs.NOTE: Administrators will see all webs, not just the public ones

public

subwebs="Sandbox"

Specifies a single web. If specified, then public and webtemplate (described above) will expand relative to show subwebs *below this web only.

""

selection="%WEB%"

Entry to be selected in list. If one of the webs matches this selection, then $marker in the format will be expanded

selection=%WEB%

marker="selected"

Text for $marker if the item matches selection

selected="selected"

Example, creates a bullet list of all webs:

%WEBLIST{" * [[$name.%HOMETOPIC%]]"}%

Example, creates a dropdown of all public webs + Trash web, with the current web highlighted:

WEBLIST will not show a web called 'TWiki' even if it exists in the file system unless the TWikiCompatibilityPlugin is installed and activated in configure. This is done to ensure that the TWiki compatibility components such as the TWiki web are only visible and active when needed