Macros

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

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)

Using Macros

• type %T% to get (a preference settings)
• type %TOPIC% to get Macros (a predefined macro)
• type %CALC{ "$UPPER(Text)" }% to get TEXT (CALC is a macro defined by SpreadSheetPlugin)

• To leave a macro unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%
  • Alternatively, insert a <nop> anywhere in the macro, Eg. %<nop>TOPIC%
• Macros are expanded relative to the topic they are used in, not the topic they are defined in
• Type %ALLVARIABLES% to get a full listing of all macros defined for a particular topic
• If a macro is not defined, then it will be left in the text unless it is called with a default parameter, in which case the value of the default parameter will replace the macro call in the output. For example, %UNDEFINED{default="blank"}% will expand to blank.

Order of expansion

• Preference settings
• Most macros provided by plugins (those that use registerTagHandler())

  Not those that use commonTagsHandler()

• Most built-in Foswiki macros

  Notable exceptions include: CALC, STARTSECTION/ENDSECTION, STARTINCLUDE/STOPINCLUDE

Standard form

%MACRO1{
   something="%MACRO2{
      somethingelse="%MACRO3%, %MACRO4%"
   }%"
}%

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

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.

%MACRO1{
   format="$percentMACRO2{
      format=\"%MACRO3%, %MACRO4%\"
   }$percent"
}%

Animated 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://matisse.oca.eu/foswiki/bin/../pub/System/DocumentGraphics/info.png"/> [[AccessKeys]]
   * <img src="https://matisse.oca.eu/foswiki/bin/../pub/System/DocumentGraphics/gear.png"/> [[AdminSkillsAssumptions]]
----
   * Set PARENT = UserDocumentationCategory

Macro Names

Preference Settings

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

Example:

   * Set WEBBGCOLOR = #FFFFC0

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 Main.WikiGuest)
5. WebPreferences
6. Sub-webs inherit the WebPreferences of their parent
7. In the topic being accessed

Writing preference settings

   * Set MYSETTING = My setting value

   * Set MACRONAME = value starts here
     and continues here

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

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

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

   * #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser

Hiding preference settings

<!--
   * Set HIDDEN = This will be invisible in the output
-->

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

Preference settings and topic revision history

Parameters

   * Set CONDITIONS = According to [[%BASETOPIC%]] the %WHAT% is %STATE% today (Set in ...).

• %CONDITIONS{WHAT="sea" STATE="choppy"}%
  • expands to According to Macros, The sea is choppy today. (Set in Macros)..

Parameter defaults

• The special parameter name DEFAULT gets the value of any unnamed parameter in the macro call.
• Parameter macros can accept a default parameter so that they expand to something even when a value isn't passed for them in the call.

   * Set WEATHER = It's %DEFAULT{default="raining"}%.

• %WEATHER% expands to It's raining.
• %WEATHER{"sunny"}% expands to It's sunny.

Access Control Settings

Local values for preferences

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20

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

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

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

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

ACTIVATEDPLUGINS -- list of currently activated plugins

Examples

• %ACTIVATEDPLUGINS% expands to SpreadSheetPlugin, SlideShowPlugin, AutoViewTemplatePlugin, CommentPlugin, CompareRevisionsAddonPlugin, ConfigurePlugin, EditRowPlugin, HistoryPlugin, HomePagePlugin, InterwikiPlugin, JQueryPlugin, MailerContribPlugin, NatEditPlugin, PreferencesPlugin, PubLinkFixupPlugin, RenderListPlugin, SmiliesPlugin, SubscribePlugin, TablePlugin, TinyMCEPlugin, TwistyPlugin, UpdatesPlugin, WysiwygPlugin

ADDTOHEAD -- deprecated, use ADDTOZONE instead

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

ALLVARIABLES -- list of currently defined macros

ATTACHURL -- full URL for attachments in the current topic

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

AUTHREALM -- authentication realm

Examples

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

BASETOPIC -- base topic where an INCLUDE started

BASEWEB -- base web where an INCLUDE started

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

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

CALCULATE -- add spreadsheet formulae calls using standard Macro evaluation order.

Examples

• • %CALCULATE{"$EXISTS(Web.SomeTopic)"}% returns 1 if the topic exists
  • %CALCULATE{"$UPPER(Collaboration)"}% returns COLLABORATION

Related

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.

COVER -- current skin cover

Examples

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

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 TemplateTopics#TemplateTopicsVars for details.

DISPLAYTIME -- display formatted time

Parameters

Examples

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

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

• The %EDITTABLE{}% macro is handled by the EditTablePlugin
• Syntax: %EDITTABLE{ attributes }%

• Supported attributes:

  Attribute	Comment	Default
  header	Specify the header format of a new table like "|*Food*|*Drink*|". Useful to start a table with only a button	(no header)
  format	The format of one column when editing the table. A cell can be a text input field, or any of these edit field types: • Text input field (1 line):   | text, <size>, <initial value> | • Textarea input field:   | textarea, <rows>x<columns>, <initial value> | • Drop down box:   | select, <size>, <option 1>, <option 2>, etc* |   * only one item can be selected • Radio buttons:   | radio, <size*>, <option 1>, <option 2>, etc |   * size indicates the number of buttons per line in edit mode • Checkboxes:   | checkbox, <size*>, <option 1>, <option 2>, etc |   * size indicates the number of checkboxes per line in edit mode • Fixed label:   | label, 0, <label text> | • Row number:   | row, <offset> | • Date:   | date, <size>, <initial value>, <DHTML date format> | (see Date Field Type)	"text, 16" for all cells
  changerows	Rows can be added and removed if "on" Rows can be added but not removed if "add" Rows cannot be added or removed if "off"	CHANGEROWS plugin setting
  quietsave	Quiet Save button is shown if "on", hidden if "off"	QUIETSAVE plugin setting
  include	Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. Use topic or web.topic notation.	(none)
  helptopic	Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% macros can be used in the topic to specify what is shown.	(no help text)
  headerislabel	Table header cells are read-only (labels) if "on"; header cells can be edited if "off" or "0"	"on"
  editbutton	Set edit button text, e.g. "Edit this table"; set button image with alt text, e.g. "Edit table, %PUBURL%/%SYSTEMWEB%/DocumentGraphics/edittopic.gif"; hide edit button at the end of the table with "hide" (Note: Button is automatically hidden if an edit button is present in a cell)	EDITBUTTON plugin setting
  buttonrow	Set to top to put the edit buttons above the table.	bottom
  javascriptinterface	Use javascript to directly move and delete row without page refresh. Enable with "on", disable with "off".	JAVASCRIPTINTERFACE plugin setting

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

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'

ENDCOLOR -- end colored text

Examples

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

ENDINCLUDE -- end position of topic text if included

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

Parameters

Examples

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

ENDTAB -- ending marker for a tab of a tabpane

ENDTABPANE -- ending tag for tabpane widget

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

ENDTWISTYTOGGLE -- Twisty closure

Examples

ENV -- inspect the value of an environment variable

Examples

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

EXAMPLETAG -- example macro tag

Parameters

Examples

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

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

FAILEDPLUGINS -- debugging for plugins that failed to load

Examples

• %FAILEDPLUGINS%

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

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

GMTIME -- formatted Greenwich Mean Time (UTC)

Parameters

Supported special format tokens:

Examples

• %GMTIME% expands to 21 Nov 2024 - 11:01
• %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 21 Nov, 2024 - 11:01:35
  When used in a template topic, this macro will be expanded when the template is used to create a new topic. See TemplateTopics#TemplateTopicsVars for details.

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 AdminGroup, BaseGroup, DocExchangeGroup, EsoExchangeGroup, NobodyGroup, ScienceFrGroup, TWikiUsersGroup, Workshop2015Group (comma-separated list of all groups)
• %GROUPINFO{AdminGroup"}% expands to Main.AdminUser, PhilippeBerio, FlorentinMillour, PierreCruzalebes, AlexisMATTER (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 WikiGroups, to allow a group listing for various user mapping managers.

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

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 VarHTTPS 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 matisse.oca.eu

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

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://matisse.oca.eu/foswiki/bin/../pub/System/DocumentGraphics/else.png
• %ICONURL{"arrowbright"}% returns https://matisse.oca.eu/foswiki/bin/../pub/System/DocumentGraphics/arrowbright.png
• %ICONURL{"novel.pdf"}% returns https://matisse.oca.eu/foswiki/bin/../pub/System/DocumentGraphics/pdf.png
• %ICONURL{"notanicon" default="ram"}% returns https://matisse.oca.eu/foswiki/bin/../pub/System/DocumentGraphics/ram.png
• %ICONURL{"/queen/boheme.mp3"}% returns https://matisse.oca.eu/foswiki/bin/../pub/System/DocumentGraphics/mp3.png

ICONURLPATH -- URL path of small documentation graphic or icon

Parameters

Examples

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

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

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

(Including a topic) Parameters

• Examples: See IncludeTopicsAndWebPages

(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 RegularExpression that contains the text you want to keep in parenthesis, e.g. pattern="(from here.*?to here)". IncludeTopicsAndWebPages has more.	none
raw	When a page is included, normally Foswiki 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 IncludeTopicsAndWebPages

(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

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

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

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
  * Български
• Čeština
• Dansk
• Deutsch
• English
• Español
• Suomi
• Français
• Italiano
• 日本語
• 한글
• Nederlands
• Norsk
• Polski
• Português
• Português brasileiro
• Русский
• Svenska
• tlhIngan Hol
• Türkçe
• 简体中文
• 正體中文
• <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

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

Examples

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

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

MAINWEB -- deprecated synonym for USERSWEB

Deprecated. Please use %USERSWEB% instead.

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 wiki-ref-webmaster@oca.eu.
• %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.

META -- displays meta-data

Parameters

"form"

"attachments"

"moved"

"parent"

"formfield"

Related

METASEARCH -- special search of meta data

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

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 WebTopicViewTemplate and WebTopicNonWikiTemplate:

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

NONCE -- generate a nonce (developers only)

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 TemplateTopics for more details).

NOTIFYTOPIC -- name of the notify topic

Examples

• %NOTIFYTOPIC% expands to WebNotify, renders as WebNotify

PERLDEPENDENCYREPORT -- report perl module dependencies

Parameters

PLUGINDESCRIPTIONS -- list of plugin descriptions

Examples

• %PLUGINDESCRIPTIONS% expands to
  • SpreadSheetPlugin (20 Jan 2017, 1.23): Add spreadsheet calculations like "$SUM($ABOVE())" to Foswiki tables and other topic text
  • SlideShowPlugin (06 Sep 2016, 2.32): Create web based presentations based on topics with headings
  • AutoViewTemplatePlugin (2016-04-08, 1.24): Automatically sets VIEW_TEMPLATE and EDIT_TEMPLATE
  • CommentPlugin (22 Jan 2018, 2.93): Quickly post comments to a page without an edit/save cycle
  • CompareRevisionsAddonPlugin (1.114, 1.114):
  • ConfigurePlugin (08 Dec 2017, 1.09): configure interface using json-rpc
  • EditRowPlugin (5 Feb 2018, 3.321): Inline edit for tables
  • HistoryPlugin (22 Jan 2018, 1.14): Shows a complete history of a topic
  • HomePagePlugin (1.23, 1.23): Allow User specified home pages - on login
  • InterwikiPlugin (8 Dec 2017, 1.25): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
  • JQueryPlugin (2 May 2019, 9.10): jQuery JavaScript library for Foswiki
  • MailerContribPlugin (2.84, 2.84): Supports e-mail notification of changes
  • NatEditPlugin (25 Feb 2018, 9.21): A Wikiwyg Editor
  • PreferencesPlugin (1.16, 1.16): Allows editing of preferences using fields predefined in a form
  • PubLinkFixupPlugin (14 Sep 2015, 1.00): For non-utf-8 sites, fix up Pub links to use correct encoding.
  • RenderListPlugin (2.28, 2.28): Render bullet lists in a variety of formats
  • SmiliesPlugin (17 Sep 2015, 2.03): Render smilies like as icons
  • SubscribePlugin (08 Dec 2017, 3.6): This is a companion plugin to the MailerContrib. It allows you to trivially add a "Subscribe me" link to topics to get subscribed to changes.
  • TablePlugin (22 Jan 2018, 1.160): Control attributes of tables and sorting of table columns
  • TinyMCEPlugin (1.31, 1.31): Integration of the Tiny MCE WYSIWYG Editor
  • TwistyPlugin (1.63, 1.63): Twisty section Javascript library to open/close content dynamically
  • UpdatesPlugin (22 Jan 2018, 1.04): Checks Foswiki.org for updates
  • WysiwygPlugin (08 Dec 2017, 1.37): Translator framework for WYSIWYG editors

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

Examples

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

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

Parameters

Examples

• Example with topic link:

  %POPUPWINDOW{"Macros" 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

PUBURL -- generate an URL for an attachment

Parameters

Examples

• %PUBURL% expands to https://matisse.oca.eu/foswiki/bin/../pub
• %PUBURL{"icon_plus.png"}% expands to =%PUBURL{"icon_plus.png"}%
• %PUBURL{web="System"}% expands to https://matisse.oca.eu/foswiki/bin/../pub/System
• %PUBURL{topic="System.MainFeatures"}% expands to https://matisse.oca.eu/foswiki/bin/../pub/System/MainFeatures
• %PUBURL{web="System" topic="MainFeatures"}% expands to https://matisse.oca.eu/foswiki/bin/../pub/System/MainFeatures
• %PUBURL{topic="System.MainFeatures"}% expands to https://matisse.oca.eu/foswiki/bin/../pub/System/MainFeatures
• %PUBURL{topic="System.MainFeatures" "icon_plus.png"}% expands to https://matisse.oca.eu/foswiki/bin/../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 /foswiki/bin/../pub
• %PUBURLPATH{"icon_plus.png"}% expands to =%PUBURLPATH{"icon_plus.png"}%
• %PUBURLPATH{web="System"}% expands to /foswiki/bin/../pub/System
• %PUBURLPATH{topic="System.MainFeatures"}% expands to /foswiki/bin/../pub/System/MainFeatures
• %PUBURLPATH{web="System" topic="MainFeatures"}% expands to /foswiki/bin/../pub/System/MainFeatures
• %PUBURLPATH{topic="System.MainFeatures" "icon_plus.png"}% expands to /foswiki/bin/../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.

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.

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 18.118.140.78

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.

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

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.

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 - ProjectContributor
• %REVINFO{"$n      * $topic: $date"}% expands to
  • VarREVINFO: 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)

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 Foswiki 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://matisse.oca.eu/foswiki/bin/view/Cartoons/EvilMonkey
• %SCRIPTURL{"view" web="Cartoons"}% will expand to https://matisse.oca.eu/foswiki/bin/view/Cartoons?web=Cartoons
• %SCRIPTURL{"view" topic="Cartoons.EvilMonkey" rev="1"}% will expand to https://matisse.oca.eu/foswiki/bin/view/Cartoons/EvilMonkey?rev=1
• %SCRIPTURL{"edit" web="Cartoons" topic="EvilMonkey" t="%GMTIME{"$epoch"}%"}% expands to https://matisse.oca.eu/foswiki/bin/edit/Cartoons/EvilMonkey?t=1732186895
• %SCRIPTURL% expands to https://matisse.oca.eu/foswiki/bin
• %SCRIPTURL{script}% expands to https://matisse.oca.eu/foswiki/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 /foswiki/bin/view/Cartoons/EvilMonkey
• %SCRIPTURLPATH{"view" web="Cartoons"}% expands to /foswiki/bin/view/Cartoons?web=Cartoons
• %SCRIPTURLPATH{"view" topic="Cartoons.EvilMonkey" rev="1"}% will expand to /foswiki/bin/view/Cartoons/EvilMonkey?rev=1
• %SCRIPTURLPATH{"edit" web="Cartoons" topic="EvilMonkey" t="%GMTIME{"$epoch"}%"}% expands to /foswiki/bin/edit/Cartoons/EvilMonkey?t=1732186895
• %SCRIPTURLPATH% expands to /foswiki/bin
• %SCRIPTURLPATH{script}% expands to /foswiki/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.

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 TablePlugin's %TABLE{}% macro placed just before the %SEARCH{}%. Example: %TABLE{ tablewidth="90%" }%

SERVERINFORMATION -- report detailed web server information

Parameters

SERVERTIME -- formatted server time

Examples

• %SERVERTIME% elsnds to 21 Nov 2024 - 12:01
• %SERVERTIME{"$hou:$min"}% expands to 12:01

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

SESSIONID -- unique ID for this session

Examples

• %SESSIONID% expands to d39d9368c456e659df046d74b58e151c

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

Examples

• %SESSIONVAR% expands to SFOSWIKISID

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

SET -- set a preference setting during runtime

   * Set foo = %SEARCH{...

%SET{"foo" value="%SEARCH{..."}%

Parameters

Examples

SHOWPREFERENCE -- show where preferences are defined.

Parameters

Examples

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

   * Set ATTACHFILESIZELIMIT = "25000000"
      * ATTACHFILESIZELIMIT was defined in Main.SitePreferences

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

   * Set DENYWEBCHANGE = ""
   * Set ALLOWWEBCHANGE = "%USERSWEB%.AdminGroup"
      * ALLOWWEBCHANGE was defined in SystemFoswiki.WebPreferences

SKIN -- current skin

Examples

• %SKIN% expands to pattern
• See Skins for more information

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

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

STARTINCLUDE -- start position of topic text if included

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

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

• • type="section" - the default, used for a generic section, such as a named section used by INCLUDE.
  • type="include" - like %STARTINCLUDE% ... %STOPINCLUDE% except that you can have as many include blocks as you want which are all merged into one when included (%STARTINCLUDE% is restricted to only one). Sections of type include may not be given a name.
  • type="expandvariables" - all macros inside an "expandvariables" type section gets expanded when a new topic based on the template topic is created. See TemplateTopics for more information.
  • type="templateonly" - start position of text to be removed when a template topic is used. This is used to embed text that you do not want expanded when a new topic based on the template topic is created. See TemplateTopics for more information.

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

STATISTICSTOPIC -- name of statistics topic

Examples

• %STATISTICSTOPIC% expands to WebStatistics, renders as WebStatistics

STOPINCLUDE -- Alias for ENDINCLUDE

STOPSECTION -- Alias for ENDSECTION

SUBSCRIBE{ attributes } - subscribe the current user for notification of changes to the current topic

• %SUBSCRIBE{...}% or simply %SUBSCRIBE%

  Parameter	Default	Meaning
  who	Logged-in user	Who to subscribe (wikiname, no web)
  topic	Current topic	Topic to subscribe to. Wildcards may be used e.g. topic="Item*" will subscribe to all topics starting with Item. Use topic="Main.*" to subscribe to the WebNotify for the Main web.
  unsubscribe	Not set	If set to "on", will unsubscribe the user

SYSTEMWEB -- name of documentation web

Examples

• %SYSTEMWEB% expands to System

TAB -- tab inside a tabpane widget

Parameters

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

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

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.

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 Macros, renders as Macros

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>

TWIKIWEB -- synonym for SYSTEMWEB

Deprecated. Use %SYSTEMWEB% instead

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

TWISTYBUTTON -- Shorthand version for TWISTYSHOW & TWISTYHIDE

Parameters

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

Examples

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

• Expands as:
  moremore
  content

Related

• ENDTWISTY
• ENDTWISTYTOGGLE
• TWISTY
• TWISTYHIDE
• TWISTYSHOW
• TWISTYTOGGLE

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="div" remember="on"}%My content%ENDTWISTYTOGGLE%

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 TemplateTopics#TemplateTopicsVars 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 CommandAndCGIScripts.

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

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

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 TemplateTopics#TemplateTopicsVars for details

USERSWEB -- name of users web

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

Examples

• %USERSWEB% expands to Main

VAR -- get a preference value from another web

Parameters

Examples

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

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

WEBPREFSTOPIC -- name of web preferences topic

Examples

• %WEBPREFSTOPIC% expands to WebPreferences, renders as WebPreferences

WIKIAGENTEMAIL -- From: email address in emails sent by Foswiki.

Examples

• %WIKIAGENTEMAIL% expands to wiki-ref-master@oca.eu

WIKIAGENTNAME -- From: Name used in emails sent by Foswiki

Examples

• %WIKIAGENTNAME% expands to Wiki Administrator

WIKIHOMEURL -- site home URL

Examples

• %WIKIHOMEURL%= expands to /foswiki/bin/view/=
• Normally by default set to %SCRIPTURLPATH{"view"}%
  For the top bar logo URL use %WIKILOGOURL% defined in WebPreferences 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 TemplateTopics#TemplateTopicsVars 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 Foswiki

WIKIUSERNAME -- your Wiki username with web prefix

Parameters

Examples

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

WIKIUSERSTOPIC -- name of topic listing all registered users

Examples

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

WIKIVERSION -- the version of the installed Foswiki engine

Examples

• %WIKIVERSION% expands to v2.1.6

WIKIWEBMASTER -- feedback email address for site

Examples

• %WIKIWEBMASTER% expands to wiki-ref-webmaster@oca.eu

WIKIWEBMASTERNAME -- Name of the administrator for the site

Examples

• %WIKIWEBMASTERNAME% expands to Wiki Administrator

Shortcuts

• %BR% - line break
• %BULLET% - bullet sign
• %BB% - line break and bullet combined
• %BB2% - indented line break and bullet
• %RED% text %ENDCOLOR% - colored text (also %YELLOW%, %ORANGE%, %PINK%, %PURPLE%, %TEAL%, %NAVY%, %BLUE%, %AQUA%, %LIME%, %GREEN%, %OLIVE%, %MAROON%, %BROWN%, %BLACK%, %GRAY%, %SILVER%, %WHITE%)
• %H% - Help icon
• %I% - Idea icon
• %M% - Moved to icon
• %N% - New icon
• %P% - Refactor icon
• %Q% - Question icon
• %S% - Red star icon
• %T% - Tip icon
• %U% - Updated icon
• %X% - Alert icon
• %Y% - Done icon