Macro List Curated

System Information

ACTIVATEDPLUGINS -- list of currently activated plugins

Examples

• %ACTIVATEDPLUGINS% expands to Spread Sheet Plugin, Slide Show Plugin, Attachment List Plugin, Auto View Template Plugin, Calendar Plugin, Captcha Plugin, Comment Plugin, Compare Revisions Addon Plugin, Configure Plugin, Edit Row Plugin, Edit Table Plugin, History Plugin, Home Page Plugin, Interwiki Plugin, JQData Tables Plugin, J Query Plugin, Mailer Contrib Plugin, Markdown Plugin, Nat Edit Plugin, Preferences Plugin, Publish Plugin, Render List Plugin, Smilies Plugin, Spaced Wiki Word Plugin, Subscribe Plugin, Table Plugin, Tiny MCEPlugin, Topic Data Helper Plugin, Topic Title Plugin, Twisty Plugin, Update Attachments Plugin, Update Info Plugin, Updates Plugin, Var Cache Plugin, Wysiwyg Plugin

FAILEDPLUGINS -- debugging for plugins that failed to load

Examples

• %FAILEDPLUGINS%

PLUGINDESCRIPTIONS -- list of plugin descriptions

Examples

• %PLUGINDESCRIPTIONS% expands to
  • Spread Sheet Plugin (19 Jul 2018, 1.24): Add spreadsheet calculations like "$SUM($ABOVE())" to Foswiki tables and other topic text
  • Slide Show Plugin (09 Mar 2021, 2.40): Create web based presentations based on topics with headings
  • Attachment List Plugin (14 July 2017, 1.6): Displays a formattable list of topic attachments - from any topic - anywhere in a topic
  • Auto View Template Plugin (2016-04-08, 1.24): Automatically sets VIEW_TEMPLATE and EDIT_TEMPLATE
  • Calendar Plugin (18 Jul 2017, 2.020): Show a monthly calendar with highlighted events
  • Captcha Plugin (21 Jan 2024, 2.30): A visual challenge-response test to prevent automated scripts from using the wiki
  • Comment Plugin (06 Aug 2023, 2.95): Quickly post comments to a page without an edit/save cycle
  • Compare Revisions Addon Plugin (06 Aug 2023, 1.114):
  • Configure Plugin (06 Aug 2023, 1.12): configure interface using json-rpc
  • Edit Row Plugin (12 Jan 2024, 3.402): Inline edit for tables
  • Edit Table Plugin (06 Aug 2023, 4.47): Edit tables using edit fields, date pickers and drop down boxes
  • History Plugin (16 Nov 2020, 1.20): Shows a complete history of a topic
  • Home Page Plugin (1.23, 1.23): Allow User specified home pages - on login
  • Interwiki Plugin (06 Aug 2023, 1.27): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
  • JQData Tables Plugin (29 Apr 2024, 7.30): JQuery based progressive enhancement of tables
  • J Query Plugin (25 Apr 2023, 10.51): jQuery JavaScript library for Foswiki
  • Mailer Contrib Plugin (06 Aug 2023, 2.84): Supports e-mail notification of changes
  • Markdown Plugin (30 Apr 2024, 4.00): Markdown support for Foswiki
  • Nat Edit Plugin (11 Jul 2023, 9.63): A Wikiwyg Editor
  • Preferences Plugin (1.16, 1.16): Allows editing of preferences using fields predefined in a form
  • Publish Plugin (28 July 2022, 3.6): Generate static output (HTML, PDF) optionally upload (FTP) the output to a publishing site.
  • Render List Plugin (06 Aug 2023, 2.29): Render bullet lists in a variety of formats
  • Smilies Plugin (17 Sep 2015, 2.03): Render smilies like as icons
  • Spaced Wiki Word Plugin (12 July 2017, 1.1): Space out Wiki Word links automatically
  • Subscribe Plugin (06 Aug 2023, 3.7): This is a companion plugin to the Mailer Contrib. It allows you to trivially add a "Subscribe me" link to topics to get subscribed to changes.
  • Table Plugin (22 Jan 2018, 1.160): Control attributes of tables and sorting of table columns
  • Tiny MCEPlugin (11 Feb 2019, 1.32): Integration of the Tiny MCE WYSIWYG Editor
  • Topic Data Helper Plugin (1.1.4, $Rev: 13567 (2012-01-09) $): helper plugin for collecting, filtering and sorting data objects
  • Topic Title Plugin (21 Jan 2024, 3.0): Free-form title for topics
  • Twisty Plugin (29 Jun 2023, 3.00): Twisty section Javascript library to open/close content dynamically
  • Update Attachments Plugin (3.13, 3.13): A batched alternative to Auto Attachments (adds and removes attachements).
  • Update Info Plugin (3.1, $Rev: 14950 (2012-06-05) $): Add a %ISNEW% tag after a Wiki Word to get a visual display of whether the linked topic was created or updated recently
  • Updates Plugin (12 Nov 2019, 2.00): Checks Foswiki.org for updates
  • Var Cache Plugin (1.2, $Rev: 14435 (2012-03-23) $): Caches the results of expanding macros in selected topics for improved server performance
  • Wysiwyg Plugin (13 Jun 2018, 1.38): Translator framework for WYSIWYG editors

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

Examples

• %PLUGINVERSION{"InterwikiPlugin"}% expands to 1.27
• %PLUGINVERSION% to get the version of the API, expands to 2.4

ENV -- inspect the value of an environment variable

Examples

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

STATISTICSTOPIC -- name of statistics topic

Examples

• %STATISTICSTOPIC% expands to WebStatistics, renders as WebStatistics

TOPICLIST -- topic index of a web

Parameters

Examples

   Create a bullet list of all topics:
   %TOPICLIST{"   * $web.$topic"}%

   Create a comma separated list of all topics:
   %TOPICLIST{separator=", "}%

   Create an option list (for drop down menus):
   %TOPICLIST{" <option>$topic</option>"}%

   Create an option list of web topics with the current topic selected:
   <select>%TOPICLIST{
      " <option $marker value='$topic'>$topic</option>"
      separator=" "
      selection="%TOPIC%"
   }%</select>

VAR -- get a preference value from another web

Parameters

Examples

• %VAR{"WEBBGCOLOR"}% expands to #B9DAFF
• %VAR{"WEBBGCOLOR" web="Main"}% expands to #FFEFA6

Paths

ATTACHURL -- full URL for attachments in the current topic

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

COVER -- current skin cover

Examples

• %COVER% currently expands to %COVER% (it will only expand when a cover is actually set)

HTTP -- get HTTP headers

• Called with the name of an HTTP request header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.
• Request headers are sent by the browser to the server. It is not possible to access the Response headers returned to the browser.
• Only returns headers permitted by site configuration. Returns '' if the header is not allowed.
• When called without a parameter, nothing is returned. See Var HTTPS for other options.

The HTTP and HTTPS macros are deprecated as of Foswiki release 2.1. and will be removed in a future release.

Parameters

Examples

You can see the HTTP headers your browser sends to the server on a number of sites e.g. http://www.ericgiguere.com/tools/http-header-viewer.html

HTTP_HOST -- environment variable

Examples

• %HTTP_HOST% expands to copswiki.org

HTTPS -- get HTTPS headers

• Called with the name of an HTTP request header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.
• Request headers are sent by the browser to the server. It is not possible to access the Response headers returned to the browser.
• Only returns headers permitted by site configuration.
• When called without a parameter, nothing is returned. See Var HTTPS for other options.

The HTTP and HTTPS macros are deprecated as of Foswiki release 2.1. and will be removed in a future release.

Parameters

Examples

You can see the HTTP headers your browser sends to the server on a number of sites e.g. http://www.ericgiguere.com/tools/http-header-viewer.html

PUBURL -- generate an URL for an attachment

Parameters

Examples

• %PUBURL% expands to https://copswiki.org/w/pub
• %PUBURL{"icon_plus.png"}% expands to =%PUBURL{"icon_plus.png"}%
• %PUBURL{web="System"}% expands to https://copswiki.org/w/pub/System
• %PUBURL{topic="System.MainFeatures"}% expands to https://copswiki.org/w/pub/System/MainFeatures
• %PUBURL{web="System" topic="MainFeatures"}% expands to https://copswiki.org/w/pub/System/MainFeatures
• %PUBURL{topic="System.MainFeatures"}% expands to https://copswiki.org/w/pub/System/MainFeatures
• %PUBURL{topic="System.MainFeatures" "icon_plus.png"}% expands to https://copswiki.org/w/pub/System/MainFeatures/icon_plus.png
• Also supports topic_version and attachment_version parameters. These can be used with advanced store implementations to select specific attachment versions. However simple file-based stores do not normally support them.
  The 'old' way of building URLs using PUBURL involved concatenating the web and topic names to the PUBURL e.g. %PUBURL%/Main/SystemFeatures. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace all such URLs with the equivalent %PUBURL%{topic="System.MainFeatures"}%, which will handle URL encoding for you.
  
  ATTACHURL provides a shorter way to refer to the attachments on the current topic.

PUBURLPATH -- generate a relative URL for an attachment

Parameters

Examples

• %PUBURLPATH% expands to /w/pub
• %PUBURLPATH{"icon_plus.png"}% expands to =%PUBURLPATH{"icon_plus.png"}%
• %PUBURLPATH{web="System"}% expands to /w/pub/System
• %PUBURLPATH{topic="System.MainFeatures"}% expands to /w/pub/System/MainFeatures
• %PUBURLPATH{web="System" topic="MainFeatures"}% expands to /w/pub/System/MainFeatures
• %PUBURLPATH{topic="System.MainFeatures" "icon_plus.png"}% expands to /w/pub/System/MainFeatures/icon_plus.png
• Also supports topic_version and attachment_version parameters. These can be used with advanced store implements to select specific attachment versions. However simple file-based stores do not normally support them.

This macro will only generate a relative URL if the store supports them, and the context allows it. Otherwise it will generate the same as PUBURL

The 'old' way of building URLs using PUBURLPATHPATH involved concatenating the web and topic names to the PUBURLPATH e.g. %PUBURLPATH%/%WEB%/%TOPIC%. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace all such URLs with the equivalent %PUBURLPATH%{topic="System.MainFeatures"}%, which will handle URL encoding for you.

ATTACHURLPATH provides a shorter way to refer to the attachments on the current topic.

SCRIPTNAME -- name of current script

• The name of the current script is shown, including script suffix, if any (for example viewauth.cgi)

Examples

• %SCRIPTNAME% expands to view

SCRIPTSUFFIX -- script suffix

• Some Cops installations require a file extension for CGI scripts, such as .pl or .cgi

Examples

• %SCRIPTSUFFIX% expands to

SCRIPTURL -- URL of script(s)

Parameters

Examples

• %SCRIPTURL{"view" topic="Cartoons.EvilMonkey"}% will expand to https://copswiki.org/Cartoons/EvilMonkey
• %SCRIPTURL{"view" web="Cartoons"}% will expand to https://copswiki.org/Cartoons?web=Cartoons
• %SCRIPTURL{"view" topic="Cartoons.EvilMonkey" rev="1"}% will expand to https://copswiki.org/Cartoons/EvilMonkey?rev=1
• %SCRIPTURL{"edit" web="Cartoons" topic="EvilMonkey" t="%GMTIME{"$epoch"}%"}% expands to https://copswiki.org/w/bin/edit/Cartoons/EvilMonkey?t=1732178805
• %SCRIPTURL% expands to https://copswiki.org/w/bin
• %SCRIPTURL{script}% expands to https://copswiki.org/w/bin/script

In most cases you should use SCRIPTURLPATH instead, as it works much better with URL rewriting

The edit script should always be used in conjunction a t="%GMTIME{"$epoch"}%" parameter to ensure pages about to be edited are not cached in the browser

The 'old' way of building URLs using SCRIPTURL involved concatenating the web and topic names to the SCRIPTURL e.g. %SCRIPTURL{"script"}%/Cartoons/EvilMonkey. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace all such URLs with the equivalent %SCRIPTURL%{"script" topic="Cartoons.EvilMonkey"}%, which will handle URL encoding for you.

The SCRIPTURL macro does NOT support building jsonrpc or rest requests with parameters. They should still use the "contatenation" method. This is expected to be fixed in Foswiki 2.2.

SCRIPTURLPATH -- URL path of script(s)

Parameters

Examples

• %SCRIPTURLPATH{"view" topic="Cartoons.EvilMonkey"}% expands to /Cartoons/EvilMonkey
• %SCRIPTURLPATH{"view" web="Cartoons"}% expands to /Cartoons?web=Cartoons
• %SCRIPTURLPATH{"view" topic="Cartoons.EvilMonkey" rev="1"}% will expand to /Cartoons/EvilMonkey?rev=1
• %SCRIPTURLPATH{"edit" web="Cartoons" topic="EvilMonkey" t="%GMTIME{"$epoch"}%"}% expands to /w/bin/edit/Cartoons/EvilMonkey?t=1732178805
• %SCRIPTURLPATH% expands to /w/bin
• %SCRIPTURLPATH{script}% expands to /w/bin/script

The edit script should always be used in conjunction with a t="%GMTIME{"$epoch"}%" parameter to ensure pages about to be edited are not cached in the browser

See SCRIPTURL if you expect to need the protocol and host e.g. if you are saving the HTML of the page and using it on a different host.

The 'old' way of building URLs using SCRIPTURLPATH involved concatenating the web and topic names to the SCRIPTURLPATH e.g. %SCRIPTURLPATH{"script"}%/Cartoons/EvilMonkey. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace such URLs with the equivalent %SCRIPTURLPATH%{"script" topic="Cartoons.EvilMonkey"}%, which will handle URL encoding for you.

The SCRIPTURL macro does NOT support building jsonrpc or rest requests with parameters. They should still use the "contatenation" method. This is expected to be fixed in Foswiki 2.2.

URLPARAM -- get URL or HTTP POST parameter value

Parameters

Examples

URL parameters passed into HTML form fields must be entity encoded.

Double quotes in URL parameters must be escaped when passed into other macros.
Example: %SEARCH{ "%URLPARAM{ "search" encode="safe, quote" }%" noheader="on" }%

Reverse the encoding when used in SEARCH.
Example: %SEARCH{ "%URLPARAM{ "search" encode="safe, quote"}%" decode="safe" noheader="on" }%. (It is not necessary to reverse quote encoding, otherwise decode= options should be specified in the reverse order from the encode= options.)

When used in a template topic, this macro will be expanded when the template is used to create a new topic. See Template Topics#Template Topics Vars for details.

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 Command And CGIScripts.

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.

Preference Settings, configuration

EXPAND -- expand macros in a string as if they were used in another topic

Parameters

Examples

   * Set MYPREFERENCE = value

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

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

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

EXPAND is not very efficient, and should be used sparingly.

To expand a web preference (for example, a web access control) then set scope="Theotherweb.%WEBPREFSTOPIC%"

LOCALSITEPREFS -- web.topicname of site preferences topic

• The full name of the local site preferences topic. These local site preferences overload the system level preferences defined in System.Default Preferences.

Examples

• %LOCALSITEPREFS% expands to Main.SitePreferences, renders as Site Preferences

MAINWEB -- deprecated synonym for USERSWEB

Deprecated. Please use %USERSWEB% instead.

NOTIFYTOPIC -- name of the notify topic

Examples

• %NOTIFYTOPIC% expands to WebNotify, renders as WebNotify

SHOWPREFERENCE -- show where preferences are defined.

Parameters

Examples

• %SHOWPREFERENCE% will show all preferences
• %SHOWPREFERENCE{"ATTACHFILESIZELIMIT"}% expands to

   * Set ATTACHFILESIZELIMIT = "1000000 "
      * ATTACHFILESIZELIMIT was *finalised* in Main.SitePreferences

• %SHOWPREFERENCE{"DENYWEBCHANGE,ALLOWWEBCHANGE"}% expands to

   * Set DENYWEBCHANGE = ""
   * Set ALLOWWEBCHANGE = "%MAINWEB%.ApprovedUsersGroup"
      * ALLOWWEBCHANGE was *finalised* in Common.WebPreferences

SKIN -- current skin

Examples

• %SKIN% expands to sidetoggle,natedit,pattern
• See Skins for more information

SYSTEMWEB -- name of documentation web

Examples

• %SYSTEMWEB% expands to System

WEBPREFSTOPIC -- name of web preferences topic

Examples

• %WEBPREFSTOPIC% expands to WebPreferences, renders as WebPreferences

WIKIHOMEURL -- site home URL

Examples

• %WIKIHOMEURL%= expands to /=
• Normally by default set to %SCRIPTURLPATH{"view"}%
  For the top bar logo URL use %WIKILOGOURL% defined in Web Preferences instead.

WIKINAME -- your Wiki username

Parameters

Examples

• %WIKINAME% expands to WikiGuest
• %WIKINAME{guest}% expands to WikiGuest
  When used in a template topic, this macro will be expanded when the template is used to create new topic. See Template Topics#Template Topics Vars for details

WIKIPREFSTOPIC -- name of site-wide preferences topic

Examples

• %WIKIPREFSTOPIC% expands to DefaultPreferences, renders as DefaultPreferences

WIKITOOLNAME -- name of your site

Examples

• %WIKITOOLNAME% expands to Cops

USERSWEB -- name of users web

• The web containing individual user topics, Wiki Groups, and customised site-wide preferences.

Examples

• %USERSWEB% expands to Main

WIKIVERSION -- the version of the installed Foswiki engine

Examples

• %WIKIVERSION% expands to v2.1.8

WIKIWEBMASTER -- feedback email address for site

Examples

• %WIKIWEBMASTER% expands to wikiadmin@cognisys.com

WIKIWEBMASTERNAME -- Name of the administrator for the site

Examples

• %WIKIWEBMASTERNAME% expands to CopsWiki Administrator

Session, Users, Groups

AUTHREALM -- authentication realm

Examples

• %AUTHREALM% expands to Enter your Wiki Name. (First name and last name, no space, no dots, capitalized, e.g. John Smith). Cancel to register if you do not have one.

GROUPINFO -- retrieve details about a group

Parameters

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.

Examples

• %GROUPINFO% expands to BaseGroup, Admin Group, Approved Users Group, Approved Viewer Group, Audience Group, Blog Admin Group, Blog Author Group, Cops Group, Event Promo Group, Nobody Group, Officers Group, People Cte Group, Progressive Strategy Group, Staff Group (comma-separated list of all groups)
• %GROUPINFO{AdminGroup"}% expands to Main.AdminUser, Raymond Lutz, Jaguar Pc, Taras Luzhnyi (comma-separated list of users in the requested group)
• groupname can optionally be qualified with the Main prefix, any other web prefix will return an empty list.

GROUPS -- a formatted list of groups

• Expands to a formatted list of user groups.
• The macro is intended to be used in Wiki Groups, to allow a group listing for various user mapping managers.

LOGIN -- present a full login link

Examples

• %LOGIN% expands to Log In

LOGOUT -- present a full logout link

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

Examples

• %LOGOUT% expands to

QUERYPARAMS -- show parameters to the query

Parameters

Examples

   %QUERYPARAMS{
     format="<input type='hidden' name='$name' value='$value' encoding="entity" />"
   }%

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 advised 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%=

Examples

• %QUERYSTRING% expands to

REMOTE_ADDR -- environment variable

Examples

• %REMOTE_ADDR% expands to 3.147.62.5

REMOTE_PORT -- environment variable

Examples

• %REMOTE_PORT% expands to

REMOTE_USER -- environment variable

Examples

• %REMOTE_USER% expands to
  Displays the user identity established by the Web Server. Not available when using Template Autentication. The REMOTE_USER variable only expands when the active script is configured to Require valid-user in the Apache configuration. Eg. If your site uses Apache authentication and allows guest access, view this page with bin/view and bin/viewauth to see the effect.

SESSIONID -- unique ID for this session

Examples

• %SESSIONID% expands to ==

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

Examples

• %SESSIONVAR% expands to

SESSION_VARIABLE -- get, set or clear a session variable

Parameters

The users ID is in the AUTHUSER session variable, and is read-only

Examples

• %SESSION_VARIABLE{"MYVAR" set="myval"}%
• %SESSION_VARIABLE{"MYVAR" clear=""}%

USERINFO -- retrieve details about a user

Parameters

Examples

• %USERINFO{"name" format="..."}% expands to guest, Main.WikiGuest, (lists $username, $wikiusername, $emails)

%USERINFO{ format="$username is really $wikiname" }%

%USERINFO{ "WikiGuest" format="$username is really $wikiname" }%

USERNAME -- your login username

The login username is considered "protected" information by default and will not be revealed to non-admin users.

Parameters

Examples

• %USERNAME% expands to guest
• %USERNAME{AdminUser}% expands to ==
  When used in a template topic, this macro will be expanded when the template is used to create a new topic. See Template Topics#Template Topics Vars for details

WIKIUSERNAME -- your Wiki username with web prefix

Parameters

Examples

• %WIKIUSERNAME% expands to Main.WikiGuest, renders as Wiki Guest
• %WIKIUSERNAME{guest}% expands to Main.WikiGuest, renders as Wiki Guest
  When used in a template topic, this macro will be expanded when the template is used to create a new topic. See Template Topics#Template Topics Vars for details

WIKIUSERSTOPIC -- name of topic listing all registered users

Examples

• %WIKIUSERSTOPIC% expands to WikiUsers
• with Main prefix renders as Wiki Users

Topic & Web Meta Information, Forms

• Data Forms

ADDTOZONE -- add content to a named zone on the page

Parameters

Parameter	Description	Default
"zone"	comma-separated list of the names of zones that the content should be added to. The only zones guaranteed to exist are head, script and body.	head
id	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	comma separated string of ids of text within this zone that this content should follow when the zone is rendered. The content will be rendered even if a specified id is missing.
text	text to be added to the named zone, mutually exclusive with topic.
topic	full qualified web.topic name that contains the text to be added, mutually exclusive with text.	%BASETOPIC%
section	section of the topic to be added	the default section between STARTINCLUDE and STOPINCLUDE

What is a "Zone"?

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

• 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

Enforcing a linear order of content within a zone

Working with {MergeHeadAndScriptZones} disabled (default)

Working with {MergeHeadAndScriptZones} enabled

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

Examples

Adding to a zone with missing dependencies

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

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

Adding Javascript to a page

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

Adding CSS to a page

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

BASETOPIC -- base topic where an INCLUDE started

BASEWEB -- base web where an INCLUDE started

FORMFIELD -- renders a field in the form attached to some topic

Parameters

• $value expands to the raw field value
• $value(display) is the form field value after mapping the stored value to the display value (use with +values form fields). If the field type does not support value mapping, renders the same as $value
• $name is the field name
• $title expands to the field title
• $formname gives the name of the form the field is in. $form is maintained for compatibility, but is deprecated
• $attributes - from the field definition
• $type - from the field definition
• $size - from the field definition
• $definingTopic - topic in which the field is defined
• The standard format tokens are also expanded

Examples

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

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

Parameters

Additional macros

• %HISTORY_REV1%: Oldest revision from the printed history
• %HISTORY_REV2%: Latest revision from the printed history
• %HISTORY_NREV%: Number of the printed revisions
• %HISTORY_MAXREV%: Latest available revision of the topic

HOMETOPIC -- home topic in each web

Examples

• %HOMETOPIC% expands to WebHome, renders as System

META -- displays meta-data

Parameters

"form"

"attachments"

"moved"

"parent"

"formfield"

Related

QUERY -- get the value of meta-data

• supports formatted access to formfields and other meta-data in topics using the same syntax as is used in IF and SEARCH statements,
• gives access to all meta-data, including that added by extensions,
• supports reporting values using JSON and other standards, simplifying the retrieval of meta-data for REST applications,
• replaces the FORMFIELD macro for most applications.

Parameters

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}"}%

• style="perl" - generates values as Perl code strings generated by running through CPAN:Data::Dumper
• style="json" - generates values as JSON strings, suitable for reading by browsers.

RENDERZONE - render the content of a zone

Parameters

$item <!--<literal> $id $missing</literal>-->

$id: requires= missing ids: $missingids

• $id - id of the ADDTOZONE call within the zone currently being rendered.
• $item - text of the ADDTOZONE call within the zone currently being rendered.
• $zone - the "zone" currently being rendered.
• $missing - if the ADDTOZONE call being rendered required any id which was not found, then $missing is the missingtoken parameter; empty string otherwise.
• $missingids - comma separated list of ids that were required by the ADDTOZONE call currently being rendered but weren't found within this zone.

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, script and body are default zones. The corresponding RENDERZONE is already included in the base foswiki.tmpl. head and script are automatically inserted before the </head> tag in the output HTML page. body is automatically inserted before the </body> tag in the output HTML page.

Macros will be expanded in all zones. TML markup will not be expanded in the head and scripts zones. Any formatting in head and scripts zones including [[TML links]] must be done directly using HTML. TML pseudo-tags like nop. verbatim, literal. and noautolink are removed from head and script zones and have no influence on the markup. All other zones will be rendered as normal topic text.

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.

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.

Examples

• %TOPIC% expands to MacroListCurated, renders as MacroListCurated

WEB -- name of current web

• %WEB% expands to the name of the web where the topic is located. If you are looking at the text of an included topic, it is the web where the included topic is located.

Examples

• %WEB% expands to System

WEBLIST -- index of all webs

Parameters

Examples

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

<form><select name="web">%WEBLIST{
      "<option $marker value='$qname'>$name</option>"
      webs="Trash, public"
      selection="%WEB%"
      separator=" "
   }% </select></form>

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

Dynamic Controls -- Interactive Content

BUTTON -- renders a nice button

Parameters

Examples

%BUTTON{
    "%MAKETEXT{"Submit"}%"
    icon="tick"
    onclick="confirm('Are your sure?')"
  }%
  %BUTTON{
    "%MAKETEXT{"Cancel"}%"
    icon="cross"
    target="%WEB%.%TOPIC%"
  }% %CLEAR%

• Expands as:
  Submit Cancel

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

Parameters

• The following standard attributes are recognized

  Name	Description	Default
  type	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 preference setting.	below
  default	Default text to put into the prompt.
  target	Name of the topic to add the comment to	the current topic
  mode	For compatibility with older versions only, synonymous with type
  nonotify	Set to "on" to disable change notification for target topics	off
  noform	Set to "on" to disable the automatic form that is generated around your comment prompt if you don't provide a FORM template. See CommentPluginExamples:noform for an example.	off
  nopost	Set to "on" to disable insertion of the posted text into the topic.	off
  remove	Set to "on" to remove the comment prompt after the first time it is clicked.	off
  button	Button label text	Add comment

Examples

• A %COMMENT% without parameters shows a simple text box.

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

• The %EDITTABLE{}% macro is handled by the Edit Table Plugin
• Syntax: %EDITTABLE{ attributes }%

• Supported attributes:

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

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

• The %IMAGEGALLERY{"topic"}% macro is handled by the Image Gallery Plugin.
• Syntax: %IMAGEGALLERY{"topic" options...}%
• Examples:
  • =%IMAGEGALLERY{"System.DocumentGraphics" columns="3" limit="12" exclude="arrow" sort="name"}%
• Related: Image Gallery Plugin

Javascript Query

JQPLUGINS -- display a summary of available plugins

Parameters

Examples

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

• JQuery Plugins:
  • Slimbox v2.05 was developed by Christophe Beyls
  • Treeview v1.4 was developed by Joern Zaefferer

JQREQUIRE -- enable a plugin on the current page

in case of an error JQREQUIRE will produce an inline HTML error message.

Parameters

Examples

• %JQREQUIRE{"easing,sliding,falling"}%

JQTHEME -- switch jQuery UI theme

in case of an error JQTHEME will produce an inline HTML error message.

Parameters

JQICON -- render an image

Parameters

%JQICON{"tick" alt="alternative content" title="this is a tick icon"}%
%JQICON{"cross"}%
%JQICON{"disk"}%
%JQICON{"star"}%
%JQICON{"lightbulb"}%
%JQICON{"camera"}%
%JQICON{"date"}%
%JQICON{"heart" animate="bounce"}%

%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"}%

JQICONPATH -- render the url path to an image icon

%JQICON{"name" format="$iconPath"}%

Examples

Tabs

TABPANE -- tabpane widget

%TABPANE%
 %TAB{"tab 1"}%
   ...
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%

%TABPANE%
 %TAB{"tab 1"}%
   %TABPANE%
     %TAB{"tab 1.1"}%
       ...
     %ENDTAB%
     %TAB{"tab1.2"}%
       ...
     %ENDTAB%
   %ENDTABPANE%
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%

Parameters

Examples

TAB -- tab inside a tabpane widget

Parameters

ENDTAB -- ending marker for a tab of a tabpane

ENDTABPANE -- ending tag for tabpane widget

Pop Up.

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

Parameters

Examples

• Example with topic link:

  %POPUPWINDOW{"MacroListCurated" label="Open this topic in a new window"}%

  Generates: Open this topic in a new window
• Example with URL:

  %POPUPWINDOW{url="https://foswiki.org"}%

  Generates: https://foswiki.org
• Enable POPUPWINDOW by writing %JQREQUIRE{"popupwindow"}% on the page

Slide Show

SLIDESHOWEND -- end slideshow

Examples

SLIDESHOWSTART -- convert a topic with headings into a slideshow

Parameters

Examples

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

• Expands as:

Slide 1: Sample Slide 1

• Bullet 1
• Bullet 2

Slide 2: Sample Slide 2

• Bullet 1
• Bullet 2

Twisty

TWISTY -- generate content block with interactive visibility controls

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	"block" or "inline" 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 block as well to create valid HTML markup.	<block>
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 Document Graphics 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 Document Graphics 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 Document Graphics 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 Document Graphics 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).
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 element
linkclass	CSS class name for link
prefix	Text to display before the show/hide links
suffix	Text to display after the show/hide links

TWISTYBUTTON -- Shorthand version for TWISTYSHOW & TWISTYHIDE

Parameters

• noscript and class (only used for 'toggle' content)
• mode button mode defaults to "block"

Examples

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

• Expands as:
  moremore
  content

Related

TWISTYHIDE - Hide/close link

Parameters

Examples

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

TWISTYSHOW - Show/open link

Parameters

Examples

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

TWISTYTOGGLE -- Twisty Toggle contents section

Parameters

Examples

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

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

ENDTWISTYTOGGLE -- Twisty closure

Examples

Spreadsheet & Table

CALC -- add spreadsheet calculations to tables and outside tables

• This macro is specifically for manipulating data in tables, and so is evaluated after the normal Macro expansion order. If you need a standard ordered evaluation see CALCULATE

Examples

• %CALC{"$SUM($ABOVE())"}% returns the sum of all cells above the current cell
• %CALC{"$EXISTS(Web.SomeTopic)"}% returns 1 if the topic exists
• %CALC{"$UPPER(Collaboration)"}% returns COLLABORATION

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

Attributes for tables

Attributes for table sorting

Attributes for table cells

Attributes for data cells

Attributes for headers

Other attributes

Examples

 %TABLE{ sort="off" tableborder="0" cellpadding="4" cellspacing="3" cellborder="0" }%
 | *A1* | *B1* |
 | A2   | B2   |

• Expands as:

  A1	B1
  A2	B2

Date & Time

DATE -- signature format date

Examples

• %DATE% expands to 21 Nov 2024
• Date format defined as {DefaultDateFormat} in configure
  When used in a template topic, this variable will be expanded when the template is used to create a new topic. See Template Topics#Template Topics Vars for details.

DISPLAYTIME -- display formatted time

Parameters

Examples

• %DISPLAYTIME% expands to 21 Nov 2024 - 08:46
• %DISPLAYTIME{"$hou:$min"}% expands to 08:46

GMTIME -- formatted Greenwich Mean Time (UTC)

Parameters

Supported special format tokens:

Examples

• %GMTIME% expands to 21 Nov 2024 - 08:46
• %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 21 Nov, 2024 - 08:46:50
  When used in a template topic, this macro will be expanded when the template is used to create a new topic. See Template Topics#Template Topics Vars for details.

SERVERTIME -- formatted server time

Examples

• %SERVERTIME% elsnds to %DATETIME{"$year-$mo-$day $hours:$minutes:$seconds"}%
• %SERVERTIME{"$hou:$min"}% expands to %DATETIME{"$year-$mo-$day $hours:$minutes:$seconds"}%

Note: When used in a template topic, this macro will be expanded when the template is used to create a new topic. See Template Topics#Template Topics Vars for details.

Topic Content Processing

ENCODE -- encode characters in a string

Parameters

Parameter	Description	Default
"string"	String to encode	"" (empty string)
type	Use a predefined encoding (see below).	Default is 'url'. Parameter type not be used if old or new are given.
old	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	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

Predefined encodings

• type="entity" or type="entities" Encode special characters into HTML entities, like a double quote into "
  • all non-printable ASCII characters below space, except newline ("\n") and carriage return ("\r").
  • HTML special characters "<", ">", "&", single quote (') and double quote (")
  • TML special characters "%", "[", "]", "@", "_", "*", "=", "$" and "|"
• type="html" As type="entity" except it also encodes \n (newline) and carriage return ("\r").
• type="safe" Encode just the characters '"<>% into HTML entities.
• type="quote" or type="quotes" Escapes double quotes with backslashes (\"), does not change any other characters
• type="url" (default) Encode special characters for use in URL parameters, like a double quote into %22.

Examples

• %ENCODE{"spaced name"}% expands to spaced%20name
• %ENCODE{"| Blah | | More blah |" old="|,$n" new="&#124;,<br />"}% expands to =| Blah | | More blah | - this encoding is useful to protect special TML characters in tables.
• %ENCODE{"10xx1x01x" old="1,x,0" new="A,,B"}% expands to ABABA
• %ENCODE{"1,2" old="$comma" new=";"}% expands to 1;2

<input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />

%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%

When using old and new, be aware that the results of applying earlier tokens are not processed again using later tokens. For example:

   %ENCODE{"A" old="A,B" new="B,C"}% will result in 'B' (not 'C'),
   %ENCODE{"asd" old="as,d" new="d,f"}% will yield 'df', and
   %ENCODE{"A" old="A,AA" new="AA,B"}% will give 'AA' and.
   %ENCODE{"asdf" old="a,asdf" new="a,2"}% will give 'asdf'

EXAMPLETAG -- example macro tag

Parameters

Examples

• %EXAMPLETAG{"hello" format="| $topic: $summary |"}%

FORMAT -- format a list of objects

Parameters

Examples

   %FORMAT{"one,two,three" type="string" format="   * $item"}%
   %FORMAT{"%SKIN%"
      header="the Skin setting is evaluated in this order:"
      format="   1 =$topic="
      footer="   1 =default="
   }%

Supported formatting tokens

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

IF -- simple conditionals

Examples

• %IF{"CONDITION" then="THEN" else="ELSE"}% shows
  "THEN" if "CONDITION" evaluates to TRUE, otherwise "ELSE" will be shown

 %IF{"defined FUNFACTOR"
   then="FUNFACTOR is defined"
   else="FUNFACTOR is not defined"
 }%

FUNFACTOR is not defined

• More detail: If Statements

MAKETEXT -- creates text using Foswiki's I18N infrastructure

Parameters

Examples

• %MAKETEXT{string="Edit"}% expands to Edit
• %MAKETEXT{"If you have any questions, please contact [_1]." args="%WIKIWEBMASTER%"}% expands to If you have any questions, please contact wikiadmin@cognisys.com.
• %MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%SYSTEMWEB%.ResetPassword,%WIKIUSERNAME%"}% expands to Did you want to reset Main.WikiGuest's password?

Notes

• [_n] brackets are validated to a positive integer from 1 to 100.
• Missing arguments are replaced with an empty string ''.
• 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.

Plurals

• %MAKETEXT{string="Edit [*,_1,file]" args="4"}% expands to Edit 4 files

Notes on plurals

• Only 3 arguments are supported.
• The first parameter must be an asterisk. Literals quant, numf or # are not supported.
• The 2nd parameter must be the argument number
• The 3rd parameter is the word or phrase to be made plural.

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

• %NOP%
  • In normal topic text, expands to <nop>, which prevents expansion of adjacent macros and wikiwords
  • When the topic containing this is used as a template for another topic, it is removed.
• %NOP{...}% deprecated
  • In normal topic text, expands to whatever is in the curly braces (if anything).
    This is deprecated. Do not use it. Use %STARTSECTION{type="templateonly"}% .. %ENDSECTION{type="templateonly"}% instead (see Template Topics for more details).

RENDERLIST -- render bullet lists in a variety of formats

Examples

%RENDERLIST{"org" focus="Sales.WestCoastTeam"}%
      * [[Eng.WebHome][Engineering]]
         * [[Eng.TechPubs][Tech Pubs]]
      * [[Sales.WestCoastTeam][Sales]]
         * [[Sales.EastCoastTeam][East Coast]]
         * [[Sales.WestCoastTeam][West Coast]]

Expands as:

Sales

East Coast

West Coast

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

Examples

• %SPACEDTOPIC% expands to Var%20*SPACEDTOPIC
  This is a deprecated macro. It can be duplicated with %ENCODE{%SPACEOUT{"%TOPIC%" separator=" *"}%}%

SPACEOUT -- renders string with spaces inserted in sensible places

Examples

• %SPACEOUT{"WebHome"}% expands to: Web Home

Parameters

Spaced out WikiWords are not automatically linked. To SPACEOUT a WikiWord but preserve the link use "double bracket" format. For example, [[WebHome][%SPACEOUT{"WebHome"}%]] expands to Web Home

TOC -- table of contents

Parameters

Preference Settings

Examples

%TOC{depth="2"}%
%TOC{"CompleteDocumentation" web="%SYSTEMWEB%" title="Contents:"}%

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.

If other topics are included using INCLUDE then any headingoffset specified on the INCLUDE macro will not be seen by TOC.

Including & Sections

STARTINCLUDE -- start position of topic text if included

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

STOPINCLUDE -- Alias for ENDINCLUDE

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

• • 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 Template Topics 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 Template Topics for more information.

Parameters

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.

Examples

• %STARTSECTION{"name"}% ................... %ENDSECTION{"name"}%
• %STARTSECTION{"name" type="section"}% .... %ENDSECTION{"name" type="section"}% (type="section" is the default)
• %STARTSECTION{type="include"}% ........... %ENDSECTION{type="include"}%
• %STARTSECTION{type="expandvariables"}% ... %ENDSECTION{type="expandvariables"}%
• %STARTSECTION{type="templateonly"}% ...... %ENDSECTION{type="templateonly"}%

ENDSECTION -- marks the end of a named section within a topic

Parameters

Examples

• %ENDSECTION{"X" type="expandvariables"}%

INCLUDE -- include another topic, or subsection of a topic, or a URL, or Foswiki embedded documentation

(Including a topic) Parameters

• Examples: See Include Topics And Web Pages

(Including a web page) Parameters

Parameter	Description	Default
"http://..."	A full qualified URL, i.e. %INCLUDE{"https://foswiki.org:80/index.html"}%. Supported content types are text/html and text/plain. If the URL resolves to an attachment file on the server this will automatically translate to a server-side include.
pattern	Include a subset of a topic or a web page. Specify a Regular Expression that contains the text you want to keep in parenthesis, e.g. pattern="(from here.*?to here)". Include Topics And Web Pages has more.	none
raw	When a page is included, normally Cops 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	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".	off
disableremoveheaders	Bypass stripping headers from included HTML (everything until first </head> tag)	off
disableremovescript	Bypass stripping all <script> tags from included HTML	off
disableremovebody	Bypass stripping the </body> tag and everything around over and below it	off
disablecompresstags	Bypass replacing newlines in HTML tags with spaces. This compression step rewrites unmatched <'s into &lt; entities unless bypassed	off
disablerewriteurls	Bypass rewriting relative URLs into absolute ones	off
warn	Warn if URL include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name) appended with the http error information.	%INCLUDEWARNING% preferences setting

JavaScript in included webpages is filtered out as a security precaution per default (disable filter with disableremovescript parameter)

Foswiki by default is configured to deny URL format includes.

• Examples: See Include Topics And Web Pages

(Including Foswiki embedded module documentation) Parameters

• Examples: See System/PerlDoc?module=Foswiki::Func

INCLUDINGTOPIC -- name of topic that includes current topic

Be careful of the subtle difference between INCLUDINGTOPIC and BASETOPIC. You probably should be using BASETOPIC

INCLUDINGWEB -- web that includes current topic

Be careful of the subtle difference between INCLUDINGWEB and BASEWEB. You probably should be using BASEWEB

Search and Format

METASEARCH -- special search of meta data

METASEARCH is deprecated in favour of the new and much more powerful query type search. See SEARCH and Query Search.

Parameters

• Examples:

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

  You may want to use this in Web Topic View Template and Web Topic Non Wiki Template:

    %METASEARCH{
      type="parent"
      web="%WEB%"
      topic="%TOPIC%"
      title="Children: "
    }%
  
    %METASEARCH{
      type="field"
      name="Country"
      value="China"
    }%

SEARCH -- search content

Parameters

Examples

• %SEARCH{"wiki" web="%USERSWEB%" scope="topic"}%

• %SEARCH{
      "FAQ"
      nonoise="on"
      header="| *Topic: * | *Summary: * |"
      format="| $topic    | $summary    |"
  }%

  (displays results in a table with header - details)

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

• Formatted Search

Revisions

REVARG -- &rev=n parameter of current request

Examples

• %REVARG% expands to (simulated) &rev=3 (actual)

REVINFO -- revision information of current topic

Examples

• %REVINFO% expands to r1 - 21 Sep 2017 - 01:45:29 - Project Contributor
• %REVINFO{"$n      * $topic: $date"}% expands to
  • Var REVINFO: 21 Sep 2017

Parameters

Examples

• %REVINFO{"$date - $wikiusername" rev="43"}%

• To get the latest revision, even when looking at an older revision:

  %REVINFO{"$rev" rev="-1"}%

REVTITLE -- The requested revision as displayed in topic breadcrumbs

Examples

• %REVTITLE% expands to (simulated) (r3) (actual)

VARCACHE{ attributes } -- cache the results of Foswiki macros in selected topics for faster page rendering

• Syntax: %VARCACHE{ "24" }%
• Supported attributes:

  Attribute	Comment	Default
  "..." or refresh="..."	Cache refresh period in hours (maximum age of cache). Accepts decimals, such as 0.25	24
  cachemsg="..."	Message shown when looking at a cached topic. Use $age to indicate the age of cache, $link to indicate the refresh URL	This topic was cached $age ago ([[$link][refresh]])
  updatemsg="..."	Message shown after a cache refresh. Use $link to indicate the refresh URL	This topic is now cached ([[$link][refresh]])

• Example: %VARCACHE{"168"}% caches the current page for 7 days
• The standard Foswiki format tokens are supported in cachmsg and updatemsg.

• Related: Var Cache Plugin, Var Cache Plugin Test
• The %VARCACHE{}% variable is handled by the Var Cache Plugin.

Language and Locale

LANG -- the language specified by the server locale

• In templates the lang attribute is defined like this:

  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="%LANG%" lang="%LANG%">

• Do not confuse LANG with LANGUAGE

Examples

• %LANG% expands to en

LANGUAGE -- language code for the current user

Avoid defining LANGUAGE in a non- per-user way, otherwise users will not be able to choose their preferred language.

Examples

• %LANGUAGE% expands to en

LANGUAGES -- list available languages

Parameters

Examples

• %LANGUAGES% expands to
  * English
• <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

Colors & Graphics

ENDCOLOR -- end colored text

Examples

• %GREEN% green text %ENDCOLOR% expands to green text

ICON -- small documentation graphic or icon of common attachment types

Parameters

Examples

• %ICON{"flag-gray"}% displays as
• %ICON{"pdf"}% displays as
• %ICON{"docx" default="doc"}% displays as
• %ICON{"smile.pdf"}% displays as
• %ICON{"/dont/you/dare/smile.pdf"}% returns
• %ICON{"data.unknown" alt="Unknown file type"}% displays as
• %ICON{"data.unknown"}% displays as
• %ICON{"http://trunk.foswiki.org/pub/System/DocumentGraphics/xsl.gif"}% displays

• Graphics: arrowbright, bubble, choice-yes, hand
• File types: bmp, doc, gif, hlp, html, mp3, pdf, ppt, txt, xls, xml, zip

• %ICON{"pdf" quote="'"}%

ICONURL -- URL of small documentation graphic or icon

Parameters

Examples

• %ICONURL% returns https://copswiki.org/w/pub/System/DocumentGraphics/else.png
• %ICONURL{"arrowbright"}% returns https://copswiki.org/w/pub/System/DocumentGraphics/arrowbright.png
• %ICONURL{"novel.pdf"}% returns https://copswiki.org/w/pub/System/DocumentGraphics/pdf.png
• %ICONURL{"notanicon" default="ram"}% returns https://copswiki.org/w/pub/System/DocumentGraphics/ram.png
• %ICONURL{"/queen/boheme.mp3"}% returns https://copswiki.org/w/pub/System/DocumentGraphics/mp3.png

ICONURLPATH -- URL path of small documentation graphic or icon

Parameters

Examples

• %ICONURLPATH{"locktopic"}% returns /w/pub/System/DocumentGraphics/locktopic.png
• %ICONURLPATH{"eggysmell.xml"}% returns /w/pub/System/DocumentGraphics/xml.png
• %ICONURLPATH{"notanicon" default="ram"}% returns /w/pub/System/DocumentGraphics/ram.png
• %ICONURLPATH{"/doc/xhtml.xsl"}% returns /w/pub/System/DocumentGraphics/xsl.png

Deprecated

ADDTOHEAD -- deprecated, use ADDTOZONE instead

ALLVARIABLES -- list of currently defined macros

TWIKIWEB -- synonym for SYSTEMWEB

Deprecated. Use %SYSTEMWEB% instead