Macros

08 Oct 2011 - 18:04 | Version 1 |

Special text strings expand on the fly to display user data or system info

Macros are text strings in one of two forms:

%MACRONAME%
%MACRONAME{ parameter="value" }%

These usually expand into content when a topic is rendered for viewing. There are two types of macros:
  1. Preference settings: May be defined and modified by the user
  2. Registered macros: Defined by the system or by Plugins (for example, the SpreadSheetPlugin introduces a %CALC{}% macro)

On this page:

Using Macros

To use a macro type its name. For example,

Note:

Order of expansion

The following describes only these types of macros:

Standard form

The key to understanding nested expressions in Foswiki is to understand that macros are expanded "inside-out, left-to-right". Example:

%MACRO1{
   something="%MACRO2{
      somethingelse="%MACRO3%, %MACRO4%"
   }%"
}%
The macros are expanded in this order: MACRO3, MACRO4, MACRO2, MACRO1.

Animated Example
%INCLUDE{
    "%QUERY{
        "'%THETOPIC%'/%THEFIELD%"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
%INCLUDE{
    "%QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
%INCLUDE{
    "%QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
%INCLUDE{
    "%QUERY{
        "'System.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
%INCLUDE{
    "FrequentlyAskedQuestion"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

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 \")

TIP When working with a given macro, consult its documentation to determine which parameters support the $percent/$percnt format tokens. Generally only output parameters like header, format and footer support format tokens.
Example:
%MACRO1{
   format="$percentMACRO2{
      format=\"%MACRO3%, %MACRO4%\"
   }$percent"
}%
The macros are expanded in this order: MACRO3, MACRO4, MACRO1, MACRO2.
Animated Example
From the conditional output example:

%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percentICON{
    \"$percentIF{
      \"'$topic'/parent.name='%PARENT%'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percentICON{
    \"$percentIF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
   * %ICON{
    "%IF{
      "'AccessKeys'/parent.name='UserDocumentationCategory'"
      then="info" else="gear"
    }%"
  }% [[AccessKeys]]
   * %ICON{
    "%IF{
      "'AdminSkillsAssumptions'/parent.name='UserDocumentationCategory'"
      then="info" else="gear"
    }%"
  }% [[AdminSkillsAssumptions]]
----
   * Set PARENT = UserDocumentationCategory
   * %ICON{
    "info"
  }% [[AccessKeys]]
   * %ICON{
    "gear"
  }% [[AdminSkillsAssumptions]]
----
   * Set PARENT = UserDocumentationCategory
   * <img src="https://www.atomikos.com/pub/System/DocumentGraphics/info.png"/> [[AccessKeys]]
   * <img src="https://www.atomikos.com/pub/System/DocumentGraphics/gear.png"/> [[AdminSkillsAssumptions]]
----
   * Set PARENT = UserDocumentationCategory

See also: FormattedSearch

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. %META:TOPICPARENT{name="AdminToolsCategory"}% #SettingPrefs

Preference Settings

A preference setting lets you define a simple macro that will be expanded in your output. A preference setting looks like this:

[multiple of 3 spaces] * [space] Set [space] MACRONAME [space] = [space] value

Example:

   * Set WEBBGCOLOR = #FFFFC0
Macros defined using preference settings are expanded by enclosing their name in percent signs. So when you write %WEBBGCOLOR%, it gets expanded to #FFD8AA

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

Preferences can be defined in a number of places:
  1. DefaultPreferences (Foswiki upgrades overwrite this topic)
  2. In (some) plugin documentation topics. (Deprecated)
  3. SitePreferences
  4. In user topics, if the user has one (yours is WikiGuest)
  5. WebPreferences
  6. Sub-webs inherit the WebPreferences of their parent
  7. In the topic being accessed
In this list, Set statements which occur at numerically higher locations override macros of the same name defined 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.

prefs-stack.jpg

Writing preference settings

Preference settings are written as a simple bullet. In TML, they are written as 3-spaces,asterisk,equals,value
   * Set MYSETTING = My setting value

When using the Wysiwyg editor, click the "Bullet" button and write the setting as a simple bullet. Don't include the asterisk.

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 (though see Parameters, below).

Example: Create a custom logo macro
   * Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif

Preference settings are case sensitive. (Foswiki by convention always writes settings in upper case.)

   * Set lower = This is LOWER
   * Set LOWER = This is UPPER
   * Set LoWeR = This is MIXED
Expand %lower%, %LOWER% and %LoWeR%
Expand %lower%, %LOWER% and %LoWeR%.

IDEA! preference settings can easily be disabled with a # sign. Example:
   * #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser

Hiding preference settings

IDEA! You can hide preference settings in the output by enclosing them in HTML comments; for example,
<!--
   * Set HIDDEN = This will be invisible in the output
-->

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.

ALERT! Caution If your topic will be used in an INCLUDE, it is recommended to not use HTML comments. instead, set preferences into the topic metadata by using the "Edit Settings for this topic" button on the "More topic actions" page. Settings in an included topic are always ignored, but nested comments will break the HTML.

Order of perference settings

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 setting anywhere in the topic, even if you set it at the very 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.

Preference settings and topic revision history

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

And especially important, preference settings are never overridden or set in "%INCLUDE{" topics. in the below example about weather conditions, note the difference in the CONDITIONS expansion

Parameters

Note that %CONDITIONS% expands differently when this example is viewed in PreferenceSettings. This is because Set statement are not active in included topics. The including topic's set statements are used.

Macros defined using preference settings can take parameters. These are symbols passed in the call to the macro to define local macros that will be expanded in the output. For example,
   * Set CONDITIONS = According to [[%BASETOPIC%]] the %WHAT% is %STATE% today (Set in ...).
You can call this macro passing in values for WHAT and STATE. For example:

Parameter defaults

Example:
   * Set WEATHER = It's %DEFAULT{default="raining"}%.
The standard formatting tokens can be used in parameters. They will be expanded immediately when the macro is instantiated.

ALERT! Note that parameters override all other macros, including system defined macros, in the expansion of the macro where they are used.

Access Control Settings

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

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.

Deprecation warning. The setting used in this example, EDITBOXHEIGHT, is being deprecated and will be remove from Foswiki 1.2. Note that if the edit box size is changed using the javascript controls in the lower right corner of the edit box window, those settings will be used, and the EDITBOX* settings will be ignored.

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.

ALERT! Predefined macros can be overridden by preference settings (except TOPIC and WEB)

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

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

Your installation of Foswiki v1.1.9 has the following registered macros:

ACTIVATEDPLUGINS -- list of currently activated plugins

ADDTOHEAD

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

ADDTOZONE

%ADDTOZONE{
  "zone"
  ...
}%

Parameters:

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:

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.

ALERT! {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
%ADDTOZONE{
  "script"
  text="
  <script type='text/javascript'>
    alert('test');
  </script>"
  requires="some-id-that-exists-in-script"
  id="MY::TEST"
}%

Result
<script type='text/javascript'>
  alert('test');
</script>
<!-- MY::TEST: requires= missing ids: some-id-that-exists-in-script -->

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:

%JQREQUIRE{"shake"}%
%ADDTOZONE{
   "script"
   id="MyApp::ShakePart"
   text="
   <script type='text/javascript'>
      jQuery('#something').shake(3, 10, 180);
   </script>"
   requires="JQUERYPLUGIN::SHAKE"
}%

where "MyApp::ShakePart" is a unique id to identify the text added to script; and JQUERYPLUGIN::SHAKE signifies that the content added with that identifier should appear beforehand.

Example: Adding CSS to a page

%ADDTOZONE{"head"
   id="MyCSS"
   text="
      <style type='text/css' media='all'>
         @import url('%PUBURLPATH%/%SYSTEMWEB%/MyCSS/foo.css');
      </style>"
}%

See also RENDERZONE, Using ADDTOZONE, Updating applications to use script zone

ALLVARIABLES -- list of currently defined macros

Deprecated 2009-04-29 in favour of SHOWPREFERENCE

AQUA -- start aqua colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

ATTACHURL -- full URL for attachments in the current topic

ATTACHURLPATH -- path of the attachment URL of the current topic

AUTHREALM -- authentication realm

BASETOPIC -- base topic where an INCLUDE started

BASEWEB -- base web where an INCLUDE started

BB -- bullet with line break

BB2 -- level 2 bullet with line break

BB3 -- level 3 bullet with line break

BB4 -- level 4 bullet with line break

BLACK -- start black colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

BLUE -- start blue colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

BR -- line break

BROWN -- start brown colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

BULLET -- bullet character

BUTTON -- renders a nice button

Parameters

Parameter Description Default
"text" text to be put on this button  
value text to be put on this button  
accesskey access key used for this button  
class extra class: use foswikiRight or foswikiLeft to specify aligment; use cyan, red, green for different background colors; use simple for a non-3D button  
href url of the click target #
icon icon to be put on the left; note, this can be any icon attached to the {IconSearchPath}; see also VarJQICON  
id html id for this button  
onclick javascript event triggered when clicking the button  
onmouseout javascript event triggered when the pointer leaves the button  
onmouseover javascript event triggered when the pointer hovers over the button  
target topic to open when clicking on the button  
title popup title displayed when hovering over the button  
type type of action to be performed; available actions are
  • button - normal click button, target specified in target or href parameter
  • clear - clears all input fields in the form that contains the button
  • reset - resets all input fields in a form to their initial value
  • submit - submits the form that contains the button
  • save - same as submit but takes care of extra validation steps when saving a wiki topic
button

Examples

%BUTTON{
    "%MAKETEXT{"Submit"}%"
    onclick="confirm('Are your sure?')"
  }%
  %BUTTON{
    "%MAKETEXT{"Cancel"}%"
    icon="cross"
    target="%WEB%.%TOPIC%"
  }% %CLEAR%
Note: BUTTONS are floating to the left by default. Take care to add a %CLEAR% after the %BUTTON{...}% so that further content does not overlap with the button.

CALC{"formula"} -- add spreadsheet calculations to tables and outside tables

CARET -- caret symbol

COMMENT{ attributes } -- insert an edit box into the topic to easily add comments.

COVER -- current skin cover

DATE -- signature format date

DISPLAYTIME{"format"} -- formatted display time

EDITACTION -- Selects an edit template

EDITTABLE{ attributes } -- edit tables using edit fields and other input fields

Example:
%EDITTABLE{ format="| text, 20 | select, 1, one, two, three |" changerows="on" }%
| *Name* | *Type* |
| Foo    | two    |

Produces: %EDITTABLE{ format="| text, 20 | select, 1, one, two, three |" changerows="on" }%
Name Type
Foo two
Related: See EditTablePlugin for more details

ENCODE{"string"} -- encodes a string

ENDCOLOR -- end colored text

ENDSECTION{"name"} -- marks the end of a named section within a topic

ENDTAB -- ending marker for a tab of a tabpane

This closes a previously opened TAB.

ENDTABPANE -- ending tag for tabpane widget

This closes a previously opened TABPANE.

ENDTWISTY -- complements an opening TWISTY tag to close a twisty

Closes an open twisty

ENDTWISTYTOGGLE -- Twisty closure

Will end the most inner unclosed Twisty Toggle section, using the proper tag

Examples

%ENDTWISTYTOGGLE%

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

EXAMPLETAG -- example variable

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,

%EXPAND{"$percentMYPREFERENCE{$quotdefault$quot param=$quotvalue$quot}" scope="SettingsTopic"}%

Notes:

FAILEDPLUGINS -- debugging for plugins that failed to load, and handler list

FORMAT{"list" format="" header="" footer="" separator=""} -- format a list of objects

Supported formatting tokens

If type="topic" (the default) the format string can contain any of the topic-specific format tokens specified in FormattedSearch ($web, $topic, $parent, $text, $locked, $date, $isodate, $index, $item, $rev, $username, $wikiname, $wikiusername, $createdate, $createusername, $createwikiname, $createwikiusername, $summary, $changes, $formname, $formfield, $pattern, $count, $ntopics, $nhits, $pager). In addition, the macro supports all the standard FormatTokens.

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.

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

FORMFIELD{"fieldname"} -- renders a field in the form attached to some topic

GMTIME{"format"} -- formatted GM time

GRAY -- start gray colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

GREEN -- start green colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

GROUPINFO{"name"} -- retrieve details about a group

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

GROUPS -- a formatted list of groups

Deprecated - do not use. Use VarGROUPINFO instead

H -- help icon

HISTORY -- control attributes of tables and sorting of table columns

The %HISTORY{}% macro is handled by the HistoryPlugin

Parameters

Parameter Description Default
"format"
format="format"
Format of one line, may include any variable which is supported by macro REVINFO r$rev - $date - $wikiusername
topic Topic name, can be in web.topic format current topic
web Web name current web
versions 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 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:
Parameter Description Default
nrev Number of revisions to show. Ignored if versions is specified, or if both rev1 and rev2 are specified. 10
rev2 Newest revision to show rev1+nrev if rev1 is specified, latest revision otherwise
rev1 Oldest revision to show rev2-nrev
reverse Show newest revisions first, if on "on"

Additional macros

The following macros are expanded 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.

HOMETOPIC -- home topic in each web

HTTP -- get HTTP headers

HTTP_HOST -- environment variable

HTTPS -- get HTTPS headers

I -- idea icon

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

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

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

IF{"condition" ...} -- simple conditionals

IMAGEGALLERY{"topic" options...} -- render an image gallery

INCLUDE{"topic"} -- include other topic.

INCLUDE{"url"} -- include a web page

INCLUDE{"doc:"} -- include Foswiki embedded module documentation

INCLUDINGTOPIC -- name of topic that includes current topic

INCLUDINGWEB -- web that includes current topic

JQICON -- render an image

Renders an icon image as found on an icon search path. The icon search path is configured Extensions tab, JQueryPlugin sub-tab in {JQueryPlugin}{IconSearchPath} and defaults to FamFamFamSilkIcons, FamFamFamSilkCompanion1Icons, FamFamFamFlagIcons, FamFamFamMiniIcons, FamFamFamMintIcons'. The named icon will be picked found first on this path of topics where icons are attached to. When the name of the icon starts with fa- like in fa-bold then icons are taken from the font-awesome iconset. Note that these icons use a different way to be inserted them into the page making resizable for one.

Parameters

Parameter Description Default
"name" name of the icon to display  
class additional css class for the img tag  
alt   alt attribute
title title attribute  
style css style format to be added to the image element
format format string used to render the icon; known variables to be used in the format string are:
  • $iconName: name as given to the name parameter
  • $iconPath: url path
  • $iconClass: css class as specified by the class parameter
  • $iconStyle: css styles as specified by the style parameter
  • $iconAlt: alt attribute-value; if the alt parameter to JQICON is set, this expands to alt='...'
  • $iconTitle: title attribute-value; if the title parameter to JQICON is set, this expands to title='...'
<img src='$iconPath' class='$iconClass' $iconAlt$iconTitle/>
Example for famfamfam icons:
%JQICON{"tick" alt="alternative content" title="this is a tick icon"}%
%JQICON{"cross"}%
%JQICON{"disk"}%
%JQICON{"star"}%
%JQICON{"lightbulb"}%
%JQICON{"camera"}%
%JQICON{"date"}%
     
Produces: alternative content cross disk star lightbulb camera date Example for font-awesome icons:
%JQICON{"fa-pagelines" style="font-size:1em;color:#00BF00"}%
%JQICON{"fa-pagelines" style="font-size:2em;color:#0FAF0F"}%
%JQICON{"fa-pagelines" style="font-size:3em;color:#1F9C1F"}%
%JQICON{"fa-pagelines" style="font-size:4em;color:#2D812D"}%
%JQICON{"fa-pagelines" style="font-size:5em;color:#315C31"}%
     
Produces:

JQICONPATH -- render the urlpath to an image

This is a shortcut for
%JQICON{"name" format="$iconPath"}%

Examples

JQPLUGINS -- display a summary of available plugins

Parameters

Parameter Description Default
"plugins" this is a regular expression that the plugin identifier must match to be displayed  
format format string to render information for each matching plugin; known variables to be used in the format string are:
  • $active state of the plugin: displays (active) when this plugin is loaded on the current page
  • $author author of the plugin
  • $documentation plugin documentation topic defaults to %SYSTEMWEB%.JQuery$name
  • $homepage link to the hompeage of this third party plugin
  • $index the current index in the list of all plugins being displayed
  • $name name of the plugin as can be used in JQREQUIRE
  • $summary short description what this plugin does; most plugins provide this piece of information in the summary section of the documentation topic
  • $tags list of TML macros this plugin implements
  • $version version of the plugin as provided by the author of this plugin
   1 <a href="$homepage">$name</a> $active $version $author
header header string prepended to the output; empty when no plugin matches  
footer footer string appended to the output; empty when no plugin matches  
separator separator put between each plugin rendered in a row $n
tagformat format string to render a link to any tag documentation a plugin implements [[%SYSTEMWEB%.Var$tag][$tag]]

Examples

 %JQPLUGINS{
   "treeview|slimbox"
   header="   * JQuery Plugins:$n"
   format="      * [[$documentation][$name]] v$version was developed by [[$homepage][$author]]"
 }%
Produces:

JQREQUIRE -- 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.
HELP in case of an error JQREQUIRE will produce an inline HTML error message.

Parameters

Parameter Description Default
"plugin,plugin,plugin" comma-separated list of plugins to be loaded  
warn (on/off) allows you to switch off warnings when a plugin was not found on

Examples

JQTHEME -- switch jQuery UI theme

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

Some Foswiki skins may come with their own jQuery UI matching the overall user experience of the web design.
HELP in case of an error JQTHEME will produce an inline HTML error message.

Parameters

Parameter Description Default
"name" name of theme: JQueryPlugin knows the following themes base, lightness, redmod, smoothness; additional themes maybe created using the themeroller and installed to /pub/System/JQueryPlugin/$name foswiki
warn (on/off) allows you to switch off warnings when a theme was not found on

LANG -- the language specified by the server locale

This macro is used to generate the lang (and xml:lang) attribute in generated HTML pages. If {UseLocale} is enabled, it is calculated from the configure setting of {Site}{Locale}. Otherwise it defaults to en (English).

LANGUAGE -- language code for the current user

LANGUAGES -- list available languages

LIME -- start lime colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

LOCALSITEPREFS -- web.topicname of site preferences topic

LOGIN -- present a full login link

LOGOUT -- present a full logout link

TIP You are already logged out, so %LOGOUT expands to an empty string

M -- moved to… icon

MAINWEB -- synonym for USERSWEB

ALERT! Deprecated. Please use %USERSWEB% instead.

MAKETEXT -- creates text using Foswiki's I18N infrastructure

Strings captured in the MAKETEXT macro are automatically mapped to the current user's selected language via locale/*.po translation files.

MAROON -- start maroon colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

META -- displays meta-data

Provided mainly for use in templates, this macro generates the parts of the topic view that relate to meta-data (attachments, forms etc.).

Syntax: %META{ "item" ...}%

Parameters:
ALERT! Use of "formfield" is deprecated in favour of the much more powerful QUERY macro.

Related: QUERY

METASEARCH -- special search of meta data

ALERT! METASEARCH is deprecated in favour of the new and much more powerful query type search. See SEARCH and QuerySearch.

MIMEICON{"filename"} -- return a meaningful icon for this filename

Examples:

video-x-generic.png video-x-generic.png video-x-generic.png video.png video.png video.png
application-pdf.png application-pdf.png application-pdf.png pdf.png pdf.png pdf.png
text-plain.png text-plain.png text-plain.png txt.png txt.png txt.png
application-zip.png application-zip.png application-zip.png zip.png zip.png zip.png
audio-x-generic.png audio-x-generic.png audio-x-generic.png sound.png sound.png sound.png

N -- "new" icon

NAVY -- start navy colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

NOP -- template text not to be expanded in instantiated topics

NOTIFYTOPIC -- name of the notify topic

NRIMAGES{"topic"} -- returns the number of images attachted to a (list of) topics

OLIVE -- start olive colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

ORANGE -- start orange colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

P -- pencil icon

PINK -- start pink colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

PLUGINDESCRIPTIONS -- list of plugin descriptions

PLUGINVERSION -- the version of a Foswiki Plugin, or the Foswiki Plugins API

POPUPWINDOW -- opens a topic or url in a new window

Parameters

Parameter Description Default
"topic"
topic="topic"
topic="web.topic"
Topic to open  
url URL to open (if topic is not used)  
label Link label the topic or the url
template View template to call when viewing a topic; not used for URLs "viewplain"
width Width of window "600"
height Height of window "480"
toolbar Show toolbars? "0"
scrollbars Show scrollbars? "1"
status Show status? "1"
location Show location bar? "0"
resizable Is the window resizable? "1"
left Left position "0"
top Top position "0"
center Center the window? "0"
menubar Show menubar? "0"
createnew Create a new window for each popup? "1"

Examples

PUBURL -- the base URL of attachments

PUBURLPATH -- the base URL path of attachments

PURPLE -- start purple colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

Q -- question icon

QUERY -- get the value of meta-data

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:

Only some configuration settings are available via QUERY: {ScriptSuffix}, {LoginManager}, {AuthScripts}, {LoginNameFilterIn}, {AdminUserLogin}, {AdminUserWikiName}, {SuperAdminGroup}, {UsersTopicName}, {AuthRealm}, {MinPasswordLength}, {Register}{AllowLoginName}, {Register}{EnableNewUserRegistration}, {Register}{NeedVerification}, {Register}{RegistrationAgentWikiName}, {AllowInlineScript}, {DenyDotDotInclude}, {UploadFilter}, {NameFilter}, {AccessibleCFG}, {AntiSpam}{EmailPadding}, {AntiSpam}{EntityEncode}, {AntiSpam}{HideUserDetails}, {AntiSpam}{RobotsAreWelcome}, {Stats}{TopViews}, {Stats}{TopContrib}, {Stats}{TopicName}, {UserInterfaceInternationalisation}, {UseLocale}, {Site}{Locale}, {Site}{CharSet}, {DisplayTimeValues}, {DefaultDateFormat}, {Site}{LocaleRegexes}, {UpperNational}, {LowerNational}, {PluralToSingular}, {EnableHierarchicalWebs}, {WebMasterEmail}, {WebMasterName}, {NotifyTopicName}, {SystemWebName}, {TrashWebName}, {SitePrefsTopicName}, {LocalSitePreferences}, {HomeTopicName}, {WebPrefsTopicName}, {UsersWebName}, {TemplatePath}, {LinkProtocolPattern}, {NumberOfRevisions}, {MaxRevisionsInADiff}, {ReplaceIfEditedAgainWithin}, {LeaseLength}, {LeaseLengthLessForceful}, {Plugins}{WebSearchPath}, {PluginsOrder}, {Cache}{Enabled}, {Validation}{Method}, {Register}{DisablePasswordConfirmation}, {SolrPlugin}{PersonDataForm}

QUERYPARAMS -- show paramaters to the query

ALERT! Security warning!

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

RED -- start red colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

REMOTE_ADDR -- environment variable

REMOTE_PORT -- environment variable

REMOTE_USER -- environment variable

RENDERLIST -- render bullet lists in a variety of formats

Expands as:
  Sales
  East Coast
  West Coast

RENDERZONE

%RENDERZONE{"zone" ...}%
See ADDTOZONE for an explanation of zones.

Parameters: Supports the standard format tokens in all parameters.

Notes:

See also ADDTOZONE for more information on zones.

REVARG -- &rev=n URL revision parameter of current topic

REVINFO -- revision information of current topic

REVINFO{"format"} -- formatted revision information of topic

REVTITLE -- (r1) The requested revision as displayed in topic breadcrumbs

S -- red star icon

SCRIPTNAME -- name of current script

SCRIPTSUFFIX -- script suffix

SCRIPTURL{"script"} -- URL of script

SCRIPTURLPATH{"script"} -- URL path of script

SEARCH{"text"} -- search content

TIP The appearance of the table emitted by the SEARCH may be controlled with TablePlugin's %TABLE{}% macro placed just before the %SEARCH{}%. Example: %TABLE{ tablewidth="90%" }%


Related topics: FormattedSearch, QuerySearch, SearchHelp, SearchPatternCookbook, RegularExpression, TOPICLIST, WEBLIST

SERVERTIME{"format"} -- formatted server time

SESSIONID -- unique ID for this session

SESSIONVAR -- name of CGI and session variable that stores the session ID

SESSION_VARIABLE -- get, set or clear a session variable

SHOWPREFERENCE -- show where preferences are defined.

Preference values are shown in a bulleted list.

SILVER -- start silver colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

SKIN -- current skin

SLIDESHOWEND -- end slideshow

The %SLIDESHOWEND% macro is handled by the SlideShowPlugin

Examples

See SLIDESHOWSTART

SLIDESHOWSTART -- convert a topic with headings into a slideshow

Handled by the SlideShowPlugin

Parameters

Parameter Description
template optional name of slide template to use

Examples

 %SLIDESHOWSTART%
 ---++ Sample Slide 1
    * Bullet 1
    * Bullet 2
 ---++ Sample Slide 2
    * Bullet 1
    * Bullet 2
 %SLIDESHOWEND%

Start presentation

Slide 1: Sample Slide 1

Slide 2: Sample Slide 2

SPACEDTOPIC -- topic name, spaced and URL-encoded deprecated

SPACEOUT{"string"} -- renders string with spaces inserted in sensible places

STARTINCLUDE -- start position of topic text if included

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

STATISTICSTOPIC -- name of statistics topic

STOPINCLUDE -- end position of topic text if included

SYSTEMWEB -- name of documentation web

T -- tip icon

TAB -- tab inside a tabpane widget

Defines a tab inside a TABPANE area; must be closed using ENDTAB.

Parameters

Parameter Description Default
"text" label of the tab Tab
before 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  

TABLE{ attributes } -- control attributes of tables and sorting of table columns

Attributes for tables

Argument Comment Default value Example
tableborder Table border width (pixels). "1" tableborder="2"
tablebordercolor 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 the table sorting user interface (clickable column headers) "on" or "off". unspecified sort="on"
initsort Column to sort initially (use "1" for the first column). If specified, sorting is enabled; by setting sort="off" the sorting interface can be hidden. 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". unspecified valign="top"
columnwidths Column widths: Comma delimited list of column widths, percentage or absolute pixel value. unspecified columnwidths="80%,20%"

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. Specify "none" for no colour, that is to use the colour/background of the page the table is on. "#6b7f93" headerbg="#999"
headerbgsorted Header cell background colour of a sorted column. Specify "none" for no colour, that is to use the colour/background of the page the table is on. 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. unspecified include="Main.WebHome"

TABPANE -- tabpane widget

This macro starts the tabpane, containing a series of TAB…ENDTABs and ends with ENDTABPANE. A complete tabpane normally looks like this:
%TABPANE%
 %TAB{"tab 1"}%
   ...
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%
Multiple tabpanes can be nested using the following scheme:
%TABPANE%
 %TAB{"tab 1"}%
   %TABPANE%
     %TAB{"tab 1.1"}%
       ...
     %ENDTAB%
     %TAB{"tab1.2"}%
       ...
     %ENDTAB%
   %ENDTABPANE%
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%

Parameters

Parameter Description Default
select number or id of tab to select 1
automaxexpand resizes the tabpane to the maximum height to fit into the window off
minheight when automaxexpand is enabled, this is the minimum size a tab is allowed to be resized 230
class extra class: use simple for a non-3D tabpane  
animate enables/disables animation of switching tabs off

Examples

see JQueryTabpane for more examples

TEAL -- start teal colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

TOC{"Topic"} -- table of contents

TOPIC -- name of current topic

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

TOPICURL -- shortcut to viewing the current topic

%TREEVIEW{}% displays topic children in a hierarchical tree
%TREE{}% synonym of %TREEVIEW{}%

Parameters

Parameter Description Default
web The web to search. current web
topic Specify tree's root topic. If none the entire web topics' tree is generated none
formatting Specify the formatting method
ullist is a <ul>-list, see sample UL lists
ollist is a <ol>-list, see sample OL lists
outline is an outline list, see sample Outlines
hlist is a <h n >-list of section heads, see sample Headlines
coloroutline:colorlist is an outline formatting with level values turned into colors, see sample Nested tables. Example: formatting="coloroutline:#ffeeff,#eeffee,#ffffee,#eeeeff,#ffeeee,#eeffff"
imageoutline:mode is a way to incorporate images into the outline format, specifically to display thread-like and folder views, see sample Image Trees. The general format is: imageoutline: mode : images : imageformat. Example: formatting="imageoutline:thread" or formatting="imageoutline:thread:I.gif,white.gif,T.gif,L.gif:<img src=\"$image\" border=\"0\">".
outline
excludetopic Same meaning as VarSEARCH excludetopic. Topics with excluded parent or processed like topic without parent. none
includetopic Same meaning as VarSEARCH topic. Can improve processing time. none
startlevel The depth of the tree to start showing nodes from. To hide the root node, supply startlevel="1" (root is level 0). The displayed node depths are relative to the root topic. 0 or 1 if topic is not specified
stoplevel The depth of the tree to show, relative to start level. 999
header Output the value within a <div> of class treePluginHeader. Suppressed if the tree is empty. none
footer Output the value within a <div> of class treePluginFooter. Suppressed if the tree is empty. none
zero Output the value within a <div> of class treePluginZero if the tree is empty. none
bookview List topics in BookView form. Not supported from v0.9. Instead use something like:
%TREE{topic="GrandParent" formatting="outline" format="$outnum $topic <br /> $summary <hr />"}%
none
format Specify the format for each node ( outline & coloroutline). The following pseudo-variable are supported on top of the ones described in FormattedSearch:
$spacetopic - the topic with spaces
$level - the tree depth of the topic (in whatever format)
$count - the topic's child position
$index - the index of the topic in the tree. Starts from one. Most useful when used in combination with TreeBrowserPlugin
$outnum - outline number for the topic (eg, 1.3.4.2)
$url - the current topic's URL Not supported. Use %SCRIPTURL{view}%/$web/$topic instead.
$author - the topic's last author Not supported from v0.9. Use %AUTHOR% instead.
$modTime - the topic's modification time. Not supported from v0.9. Use $date instead.
none
formatbranch - specify the format for a group of children ( outline & coloroutline)
$parent - the text of a node
$children - the text of all the node's children (if any)
none
levelprefix Specify a prefix to a node format. The prefix is inserted $level times at the beginning of the rendered node format. It allows generation of trees using Foswiki bullet list syntax thus enabling usage of TreePlugin in combination with TreeBrowserPlugin. none
nodiv Suppress the <div> around the tree. Set to 2 to suppress div around header, footer and zero. Allows for trees concatenation. none
separator Character string used to separate items in the tree \n
nocache Set to 1 to disable caching mechanism for that specific tree. Really a developer setting. 0

Examples

See the following page for sample usage and output:

TWIKIWEB -- synonym for SYSTEMWEB

ALERT! Deprecated. Use %SYSTEMWEB% instead

TWISTY -- generate content block with interactive visibility controls

This renders the button as well as the toggled content section contained within this and the closing ENDTWISTY tag.

Parameters

Parameter Description Default
id Used to link TWISTYBUTTON and TWISTYTOGGLE  
link Link label for both show and hide links  
hidelink Hide link label  
showlink Show link label  
mode "div" or "span" 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. <div>
showimgleft 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.
 
hideimgleft 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.
 
showimgright 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.
 
hideimgright 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.
 
remember If "on", the Twisty state is remembered the next time the page is shown. If "off", the stored setting will be cleared.

ALERT! 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.
 
start "hide" or "show" Initial state of the Twisty; this will override any setting stored in a cookie (see remember).  
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).  
noscript Make content hidden in case use does not have JavaScript on. Default content is shown in case JavaScript if off  
class CSS class name for Twisty div or span  
linkclass CSS class name for link  
prefix Text to display before the show/hide links  
suffix Text to display after the show/hide links  
Additional parameters img, imgleft, imgright, hideimg, showimg are deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.

TWISTYBUTTON -- Shorthand version for TWISTYSHOW & TWISTYHIDE

This is useful if both the show and the hide button take the same arguments.

Parameters

All parameters supported by TWISTY, except for

Examples

%TWISTYBUTTON{
    id="myid"
    link="more"
  }%%TWISTYTOGGLE{
    id="myid"
  }%content%ENDTWISTYTOGGLE%

Related

TWISTYHIDE - Hide/close link

Parameters

Parameter Description Default
id Used to link TWISTYSHOW, TWISTYHIDE and TWISTYTOGGLE required
link Hide link label  
mode "div" or "span" 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. <div>
img 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.
 
remember 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.
 
start "hide" or "show" Initial state of the Twisty; this will override any setting stored in a cookie (see remember).  
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).  

Examples

%TWISTYHIDE{id="demo" link=" Click to Fold " imgleft="%ICONURLPATH{toggleclose}%"}%

TWISTYSHOW - Show/open link

Parameters

Parameter Description Default
id Used to link TWISTYSHOW, TWISTYHIDE and TWISTYTOGGLE required
link Show link label  
mode "div" or "span" 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. <div>
img 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.
 
imgleft 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.
 
imgright 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.
 
remember 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.
 
start "hide" or "show" Initial state of the Twisty; this will override any setting stored in a cookie (see remember).  
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).  

Examples

%TWISTYSHOW{id="demo" link=" Click to Unfold " imgleft="%ICONURLPATH{toggleopen}%"}%

TWISTYTOGGLE -- Twisty Toggle contents section

Parameters

Parameter Description Default
id Used to link TWISTYSHOW, TWISTYHIDE and TWISTYTOGGLE. required
mode "div" or "span" 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. <div>
class CSS class name for content div or span  
linkclass CSS class name for link  
remember 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.
 
start "hide" or "show" Initial state of the Twisty; this will override any setting stored in a cookie (see remember).  
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).  
noscript hide to make content hidden in case use does not have JavaScript on  

Examples

%TWISTYTOGGLE{id="demo" mode="div" remember="on"}%My content%ENDTWISTYTOGGLE%

U -- "updated" icon

URLPARAM{"name"} -- get URL or HTTP POST parameter value

USERINFO{"name"} -- retrieve details about a user

USERNAME -- your login username

USERSWEB -- name of users web

VAR{"NAME" web="Web"} -- get a preference value from another web

VBAR -- vertical bar

WEB -- name of current web

WEBLINK

The following variables can be used in the format string:

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

WEBPREFSTOPIC -- name of web preferences topic

WHITE -- start white colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

WIKIHOMEURL -- site home URL

WIKINAME -- your Wiki username

WIKIPREFSTOPIC -- name of site-wide preferences topic

WIKITOOLNAME -- name of your site

WIKIUSERNAME -- your Wiki username with web prefix

WIKIUSERSTOPIC -- name of topic listing all registered users

WIKIVERSION -- the version of the installed Foswiki engine

WIKIWEBMASTER -- feedback email address for site

WIKIWEBMASTERNAME -- Name of the administrator for the site

WORKFLOW* -- macros associated with WorkflowPlugin

Controlling topics in the workflow
%WORKATTACHTOPIC% Expands to a link that lets you attach to the topic (if the user is not able to modify the topic, either in the workflow sense or according to the standard access controls, the link will be struck out).
%WORKFLOWEDITTOPIC% Expands to a link that lets you edit the topic (if the user is not able to modify the topic, either in the workflow sense or according to the standard access controls, the link will be struck out).
%WORKFLOWFORK{...}% Expands to a button that will create a copy of the current topic (see below for more details)
%WORKFLOWTRANSITION% Expands to either (a) a pull-down menu if the user can perform more than one transition, (b) a button if the current user can only perform one transition, or © empty space if the current user is not allowed to perform any action. You can change the format of the button using a CSS class (see WORKFLOWTRANSITIONCSSCLASS below)
Querying the workflow
%WORKFLOWHISTORY% Expands to the history of state transitions the topic has undergone. The format of the history is dictated by the WORKFLOWHISTORYFORMAT (described below).
%WORKFLOWLASTREV{"State"}% Expands to the version number when the document was last in the state State.
%WORKFLOWLASTTIME{"State"}% Expands to the timestamp when the document was last in the State state. For example, %WORKFLOWLASTTIME{"APPROVED"}% would be replaced by the timestamp when the document was last in the APPROVED state.
%WORKFLOWLASTUSER{"State"}% Expands to the last user who transitioned the document into the state State.
%WORKFLOWLASTVERSION{"State"}% Expands to a link to the version of the document when it was last in the state State.
%WORKFLOWSTATE% Expands to the current state of the document. It can also be given a topic parameter (default), in which case the state of that topic is returned.
%WORKFLOWSTATEMESSAGE% Expands to the corresponding message in the state table.

(All the macros accept an optional default parameter, which is the name of a topic, a web and a rev parameter. If these are omitted, they will default to the current topic, latest revision)

Furthermore, the plugin replaces any macro starting with WORKFLOW that is defined in the workflow description file.

If the topic is not controlled, then any references to WORKFLOW macros are simply removed (you can use this behaviour to place these tags in the header or footer in your skin templates. They appear only if the currently displayed document is controlled. Otherwise, they are just removed and do not disturb the layout).

In addition there are two macros you can define in your topics (or WebPreferences)

WORKFLOWHISTORYFORMAT tells the plugin how to format each new line added to the WORKFLOWHISTORY. The format is used as a template for each new entry, and should include all the formatting necessary to make the history look nice when it is viewed.

In this example the history is formatted as a table: The leading $n expands to a newline character that separates each line of the history. You could also format the history as a bullet list: The standard FormatTokens are supported, as well as the following special tokens:
Token Expands to
$wikiusername Who triggered the transition
$state The target state of the transition
$date Date of the transition
$rev Version at the transition

The appearance of the button to change state can be configured by providing a CSS class. For example, The default is foswikiChangeFormButton foswikiSubmit.

The WORKFLOWFORK macro is used to generate a button that will create a copy of a workflow topic. It accepts the following parameters:
Parameter Meaning Default
"TopicName" (Optional) name of the topic to fork current topic
web (Optional) name of the web containing the topic to fork current web
newnames="NameOne,NameTwo" Comma-separated list of name(s) of the new topic(s) to create, You can use a web specifier on the topic names. required, no default.
label="Fork" Label to use in the button "Fork"
lockdown="on" Set this if you want the forked topic to be set as uneditable after the fork off
This macro is used when you have a topic that has to be split to follow different routes through a workflow - for example, when a requirement is refined to create two new requirements that must follow their own lifecycles; or perhaps a problem report is found to affect two different components of a system, and the resolutions have to be separately tracked. Both the copied topic and the new topic will have workflow history entries added.

For example, %WORKFLOWFORK{"OriginalTopic" label="Divide and conquer" newnames="ForkPathOne,ForkPathTwo" lockdown="on"}% will create two copies of OriginalTopic, named ForkPathOne and ForkPathTwo and set the OriginalTopic as uneditable (using ALLOWTOPICCHANGE).

The histories in both the fork copies and the original topic record what happened.

The user has to be able to modify the topic (both in the workflow sense and according to the standard access controls) in order to fork.

ALERT! due to a bug in versions of the plugin prior to Oct 2009, the default "TopicName" parameter was interpreted as the name of the new topic to fork to. This has been corrected, but the macro will revert to the old meaning if you omit the newnames parameter.

X -- warning icon

Y -- "yes" icon

YELLOW -- start yellow colored text

Related: ENDCOLOR, DefaultPreferences, StandardColors

Shortcuts

The following macros are preference settings and are frequently used in topic content.

See ShortcutMacros for a full list of predefined shortcuts.


Related Topics: UserDocumentationCategory