type %CALC{ "$UPPER(Text)" }% to get TEXT (CALC is a macro defined by SpreadSheetPlugin)
Note:
To leave a macro unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%
Alternatively, insert a anywhere in the macro, Eg. %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
The following describes only these types of macros:
The macros are expanded in this order: MACRO3, MACRO4, MACRO2, MACRO1.
Animated Example
%INCLUDE{
"%QUERY{
"'%THETOPIC%'/%THEFIELD%"
}%"
section="Summary"
}%
* Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
* Set THEFIELD = System.TopicClassification
%INCLUDE{
"%QUERY{
"'%SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
}%"
section="Summary"
}%
* Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
* Set THEFIELD = System.TopicClassification
%INCLUDE{
"%QUERY{
"'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
}%"
section="Summary"
}%
* Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
* Set THEFIELD = System.TopicClassification
%INCLUDE{
"%QUERY{
"'System.FAQWhatIsWikiWiki'/TopicClassification"
}%"
section="Summary"
}%
* Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
* Set THEFIELD = System.TopicClassification
%INCLUDE{
"FrequentlyAskedQuestion"
section="Summary"
}%
* Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
* Set THEFIELD = System.TopicClassification
These topics are for frequently
asked questions including answers.
* Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
* Set THEFIELD = System.TopicClassification
These topics are for frequently
asked questions including answers.
* Set THETOPIC = System.FAQWhatIsWikiWiki
* Set THEFIELD = System.TopicClassification
Delayed form
Standard form macros can nearly always be used to build the parameter string of another macro; however, sometimes it is desirable to bypass the inside-out expansion order and delay the inner macro until after the outer macro has finished expansion. This is accomplished by using the $percent format token instead of %, and escaping any " character it uses (becomes \")
When working with a given macro, consult its documentation to determine which parameters support the $percent/$percntformat tokens. Generally only output parameters like header, format and footer support format tokens.
Macro names must start with a letter. The following characters can be letters, numbers and the underscore '_'. Letters may be upper or lower-case, E.g. %MYVAR%, %MyVar%, %My2ndVar%, and %My_Var% are all separate, valid macro names (macros are case sensitive - %MyVAR% and %MYVAR% are not the same).
By convention all settings, predefined macros and macros registered by plugins are always UPPER-CASE. %META:TOPICPARENT{name="AdminToolsCategory"}% #SettingPrefs
Preference Settings
A preference setting lets you define a simple macro that will be expanded in your output. A preference setting looks like this:
[multiple of 3 spaces] * [space] Set [space] MACRONAME [space] = [space] value
Example:
* Set WEBBGCOLOR = #FFFFC0
Macros defined using preference settings are expanded by enclosing their name in percent signs. So when you write %WEBBGCOLOR%, it gets expanded to #FFEFA6
A preference macro is always taken from the most current topic revision, even when accessing previous revisions of a topic.
In user topics, if the user has one (yours is WikiGuest)
WebPreferences
Sub-webs inherit the WebPreferences of their parent
In the topic being accessed
In this list, Set statements which occur at numerically higher locations override macros of the same name defined at lower numbered levels, unless the macro was listed in a finalpreferences setting (finalised) at a lower-numbered level. in this case, the macro is locked to the value at that level; set statements at higher-numbered levels are ignored.
Writing preference settings
Preference settings are written as a simple bullet. In TML, they are written as 3-spaces,asterisk,equals,value
* Set MYSETTING = My setting value
When using the Wysiwyg editor, click the "Bullet" button and write the setting as a simple bullet. Don't include the asterisk.
Spaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line.
Example:
* Set MACRONAME = value starts here
and continues here
Whatever you include in your macro will be expanded on display, exactly as if it had been entered directly (though see Parameters, below).
Example: Create a custom logo macro
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
Preference settings are case sensitive. (Foswiki by convention always writes settings in upper case.)
* Set lower = This is LOWER
* Set LOWER = This is UPPER
* Set System.LoWeR = This is MIXED
Expand %lower%, %LOWER% and %LoWeR%
Expand %lower%, %LOWER% and %LoWeR%.
preference settings can easily be disabled with a # sign. Example:
* #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser
Hiding preference settings
You can hide preference settings in the output by enclosing them in HTML comments; for example,
You can also set preference settings in a topic by clicking the link Edit topic preference settings under More topic actions. Preferences set in this manner are known as 'meta' preferences and are not visible in the topic text, but take effect nevertheless.
Caution If your topic will be used in an INCLUDE, it is recommended to not use HTML comments. instead, set preferences into the topic metadata by using the "Edit Settings for this topic" button on the "More topic actions" page. Settings in an included topic are always ignored, but nested comments will break the HTML.
Order of perference settings
If you are setting a preference and using it in the same topic, note that Foswiki reads all the preference settings from the saved version of the topic before it displays anything. This means you can use a setting anywhere in the topic, even if you set it at the very end. But beware: it also means that if you change the setting of a macro you are using in the same topic, Preview will show the wrong thing, and you must Save the topic to see it correctly.
Preference settings and topic revision history
Foswiki always reads the settings from the most current topic revision, so viewing older revisions of a topic can show unexpected results.
And especially important, preference settings are never overridden or set in "%INCLUDE{" topics. in the below example about weather conditions, note the difference in the CONDITIONS expansion
Parameters
Note that %CONDITIONS% expands differently when this example is viewed in Macros. This is because Set statement are not active in included topics. The including topic's set statements are used.
Macros defined using preference settings can take parameters. These are symbols passed in the call to the macro to define local macros that will be expanded in the output. For example,
* Set CONDITIONS = According to [[System.%BASETOPIC%][%BASETOPIC%]] the %WHAT% is %STATE% today (Set in ...).
You can call this macro passing in values for WHAT and STATE. For example:
%CONDITIONS{WHAT="sea" STATE="choppy"}%
expands to %CONDITIONS{WHAT="sea" STATE="choppy"}%.
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.
Example:
* Set WEATHER = It's %DEFAULT{default="raining"}%.
%WEATHER% expands to %WEATHER%
%WEATHER{"sunny"}% expands to %WEATHER{"sunny"}%
The standard formatting tokens can be used in parameters. They will be expanded immediately when the macro is instantiated.
Note that parameters override all other macros, including system defined macros, in the expansion of the macro where they are used.
Access Control Settings
These are special types of preference settings to control access to content. AccessControl explains these security settings in detail. Parameters are not available in access control settings.
Local values for preferences
Certain topics (user, plugin, web, site and default preferences topics) have a problem; macros defined in those topics can have two meanings. For example, consider a user topic. A user may want to use a double-height edit box when they are editing their home topic - but only when editing their home topic. The rest of the time, they want to have a normal edit box. This separation is achieved using Local in place of Set in the macro definition. For example, if the user sets the following in their home topic:
* Set EDITBOXHEIGHT = 10
* Local EDITBOXHEIGHT = 20
Then, when they are editing any other topic, they will get a 10 high edit box. However, when they are editing their home topic they will get a 20 high edit box. Local can be used wherever a preference needs to take a different value depending on where the current operation is being performed.
Use this powerful feature with great care! %ALLVARIABLES% can be used to get a listing of the values of all macros in their evaluation order, so you can see macro scope if you get confused.
Deprecation warning. The setting used in this example, EDITBOXHEIGHT, is being deprecated and will be remove from Foswiki 1.2. Note that if the edit box size is changed using the javascript controls in the lower right corner of the edit box window, those settings will be used, and the EDITBOX* settings will be ignored.
Predefined Macros
Most predefined macros return values that were either set in the configuration when Foswiki was installed, or taken from server info (such as current username, or date and time). Some, like %SEARCH%, are powerful and general tools.
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%.
Your installation of Foswiki v1.1.9 has the following registered macros:
ACTIVATEDPLUGINS -- list of currently activated plugins
This macro is deprecated. Please use VarADDTOZONE instead. It effecively is a shortcut for %ADDTOZONE{"head" ...}%
ADDTOZONE
%ADDTOZONE{
"zone"
...
}%
Parameters:
"zone" optional, comma-separated list of the names of zones that the content should be added to. The only zones guaranteed to exist are head and script. Defaults to head.
id optional, identifier for the text being added with the ADDTOZONE call, to be used in the requires parameter of other ADDTOZONE calls.
Multiple ADDTOZONE calls with the same id parameter will simply overwrite the earlier ADDTOZONE call.
requires="..." optional, comma separated string of ids of text within this zone that this content should follow when the zone is rendered. The content will be rendered even if a specified id is missing.
text="..." optional, text to be added to the named zone, mutually exclusive with topic.
topic="..." optional, full qualified web.topic name that contains the text to be added, mutually exclusive with text. Defaults to %BASETOPIC%
section="..." optional, section of the topic to be added, defaults to the default section between STARTINCLUDE and STOPINCLUDE.
What is a "Zone"?
Zones are specific places in the output HTML that are marked by calls to the RENDERZONE macro. Zones are used to collect various content together, such as Javascript and CSS, that must be included in the output HTML in a specific order, and in a specific place.
There are two special zones called head and script. The head zone is rendered as part of the HTML head section. It is the catch-all container for any content supposed to be placed into the HTML head section, except Javascript, which is collected in the script zone.
All Javascript must always be added to the script zone exclusively, in order to grant ordering constraints among scripts are resolved properly. Never add Javascript to the head zone -- never add non-Javascript content to the script zone.
Both zones are added to the HTML head section automatically just before the closing tag as if they were specified explicitly in the skin templates using:
...
%RENDERZONE{"head"}%
%RENDERZONE{"script"}%
You may create as many zones in addition to the standard head and script zones as you like. For any non-standard zone specified in ADDTOZONE you will also need to provide an appropriate RENDERZONE.
Interesting use cases in wiki applications:
Create a sidebar zone to add widgets,
Create a toolbar zone to add buttons icons
Create a menu zone to add menu entries
Adding content to a zone
ADDTOZONE adds content to a zone identified with the id parameter. An id identifier is unique within the zone that they are added to. When the same id is used in multiple calls to ADDTOZONE the last call will win, that is previous content of the same id will be overwritten.
Enforcing a linear order of content within a zone
An ADDTOZONE call may ensure that its content appears after the content of some other ADDTOZONE calls by specifying their ids in the requires parameter. The requires parameter constraints the linear order of content added to a zone. When a zone is rendered, all ordering constraints expressed via requires are satisfied. Those ids not found in a zone don't have any influence on the final ordering. Missing ids aren't considered an error rather than an over-specified ordering problem.
Working with {MergeHeadAndScriptZones} disabled (default)
In this mode, the head and script zones are treated separately.
Even when head and script zones are treated separately, the head zone will always be rendered before the script zone, unless otherwise specified using RENDERZONE explicitly. So any content in the script zone that depends on content placed into the head zone is satisfied intrinsicly as they are both rendered as specified above.
Working with {MergeHeadAndScriptZones} enabled
In this mode, the head and script zones are separate when adding to them, but may be treated as merged when you call RENDERZONE if there are any dependencies specified that only exist in the opposite zone. This allows an ADDTOZONE{"head"...} to to successfully require an id that has been added to script.
{MergeHeadAndScriptZones} is provided to maintain compatibility with legacy extensions that use ADDTOHEAD to add "
requires="some-id-that-exists-in-script"
id="MY::TEST"
}%
Result
Example: Adding Javascript to a page
Make sure that all inline Javascript code in the topic (if it is allowed) is added to the page using %ADDTOZONE{"script"...requires="library-id"}% with the appropriate library-id to guarantee a correct load order. For example, jQuery code should be added as follows:
where "MyApp::ShakePart" is a unique id to identify the text added to script; and JQUERYPLUGIN::SHAKE signifies that the content added with that identifier should appear beforehand.
AQUA is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors. Example:
%AQUA% aqua text %ENDCOLOR%
Expands to: aqua text
%% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write
%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
String defined as {AuthRealm} expert option in configure. This is used in certain password encodings, and in login templates as part of the login prompt.
Syntax: %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.
BLACK is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors. Example:
%BLACK% black text %ENDCOLOR%
Expands to: black text
%% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write
%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
BLUE is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors. Example:
%BLUE% blue text %ENDCOLOR%
Expands to: blue text
%% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write
%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
BROWN is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors. Example:
%BROWN% brown text %ENDCOLOR%
Expands to: brown text
%% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write
%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
Note: BUTTONS are floating to the left by default. Take care to add a %CLEAR% after the %BUTTON{...}% so that further content does not overlap with the button.
CALC{"formula"} -- add spreadsheet calculations to tables and outside tables
The %CALC{"formula"}% macro is handled by the SpreadSheetPlugin. There are around 90 formulae, such as $ABS(), $EXACT(), $EXISTS(), $GET()/$SET(), $IF(), $LOG(), $LOWER(), $PERCENTILE(), $TIME(), $VALUE().
Syntax: %CALC{"formula"}%
Examples:
%CALC{"$SUM($ABOVE())"}% returns the sum of all cells above the current cell
%CALC{"$EXISTS(Web.SomeTopic)"}% returns 1 if the topic exists
CODE{…} -- format and highlight syntax for displaying code fragments
The %CODE% macro and its companion %ENDCODE% macro are provided by the BeautifierPlugin and are used together to mark the beginning and ending of a code fragment to be beautifully displayed.
Syntax: %CODE% … %ENDCODE% or %CODE{…}% … %ENDCODE%
%CODE% … %ENDCODE% encapsulates a code fragment to be displayed using the default language syntax and CSS styling
%CODE{…}% … %ENDCODE% encapsulates a code fragment to be displayed allowing the language syntax and CSS styling to be overridden according to any parameters supplied
The Beautifier package supports many, many more language syntaxes but only the languages above have been ported to Foswiki at this point. If you need support for an additional syntax, please open an Enhancement Request to request the syntax you require.
DOM Structure: The beautified code fragment is encapsulated within a
element which, in turn, is encapulated within a
element which has two CSS class selectors, "fragment" and the language syntax identifier, which is itself encapsulated within a
element with the CSS class selector "BeautifierPlugin" as illustrated below.
language fragment">
… beautified code fragment …
Language-specific CSS styling can be applied to the beautified code fragment using CSS selectors of the form div.BeautifierPlugin div.language.fragment
Only one extended stylesheet may be supplied for a given topic using either the css="URL" macro parameter or the BEAUTIFIERPLUGIN_CSS preference setting. The final stylesheet specified is the one that will be used. If you wish to specify multiple customizations, combine all the CSS rules into a single stylesheet.
This is the name of the template to use for this comment. Comment templates are defined in a Foswiki template - see Customisation, below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your WebPreferences.
below
default
Default text to put into the textarea of the prompt.
target
Name of the topic to add the comment to
the current topic
location
Regular expression specifying the comment location in the target topic. Read carefully the CommentPlugin documentation!
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 encloses your comment block - remember to insert tags yourself! 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.
%COVER% extends the skin search path. For instance, if SKIN is set to catskin, bearskin, and COVER is set to ruskin, the skin search path becomes ruskin, catskin, bearskin.
The COVER setting can be overridden using the URL parameter cover, such as ?cover=ruskin
The EDITACTIONpreference setting lets you define the use of an editaction template instead of the standard edit. If EDITACTION is defined as text, then hide the form. If EDITACTION is defined as form hide the normal text area and only edit the form.
Syntax:
* Set EDITACTION = text|form
Expands to: %EDITACTION%
When EDITACTION is defined as text or form the Edit and Edit Raw buttons simply add ;action=text or ;action=form to the URL for the edit script. If you have defined an EDITACTIONpreference setting you can still edit the topic content or the form by removing the ;action=form or ;action=text from the edit URL in the browser and reload.
Rows can be added and removed if "on" Rows can be added but not removed if "add" Rows cannot be added or removed if "off"
CHANGEROWS plugin setting
quietsave
Quiet Save button is shown if "on", hidden if "off"
QUIETSAVE plugin setting
include
Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. Use topic or web.topic notation.
(none)
helptopic
Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% macros can be used in the topic to specify what is shown.
(no help text)
headerislabel
Table header cells are read-only (labels) if "on"; header cells can be edited if "off" or "0"
"on"
editbutton
Set edit button text, e.g. "Edit this table"; set button image with alt text, e.g. "Edit table, %PUBURL%/%SYSTEMWEB%/DocumentGraphics/edittopic.gif"; hide edit button at the end of the table with "hide" (Note: Button is automatically hidden if an edit button is present in a cell)
EDITBUTTON plugin setting
buttonrow
Set to top to put the edit buttons above the table.
bottom
javascriptinterface
Use javascript to directly move and delete row without page refresh. Enable with "on", disable with "off".
Encode character sequences in "string", by mapping characters (or sequences of characters) to an alternative character (or sequence of characters). This macro can be used to encode strings for use in URLs, to encode to HTML entities, to protect quotes, and for as many other uses as you can imagine.
Default is 'url'. Parameter type not be used if old or new are given.
old="tokenlist"
Comma-separated list of tokens to replace. Tokens are normally single characters, but can also be sequences of characters. The standard format tokens may be used in this list. Each token must be unique - you cannot list the same token twice.
May not be used with type; required if new is used
new="tokenlist"
comma-separated list of replacement tokens. The elements in this list match 1:1 with the elements in the old list. Again, the standard format tokens may be used. An empty element in the new list will result in the corresponding token in the old list being deleted from the string. If the new list is shorter than the old list it will be extended to the same length using the empty element. Tokens do not have to be unique.
When using old and new, be aware that the results of applying earlier tokens are not processed again using later tokens. (see examples below)
May not be used with type; required if old is used
If ENCODE is called with no optional parameters (e.g. %ENCODE{"string"}%) then the default type="url" encoding will be used.
Predefined encodings.
Unless otherwise specified, the type parameter encodes the following "special characters"
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="entity" or type="entities" Encode special characters into HTML entities, like a double quote into ". Does not encode \n (newline).
type="html" As type="entity" except it also encodes \n (newline)
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" 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="|, "}% 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
Values for HTML input fields must be entity encoded. Example:
ENCODE can be used to filter user input from URL parameters and similar to help protect against cross-site scripting. The safest approach is to use type="entity". This can however prevent an application from fully working. You can alternatively use type="safe" which encodes only the characters '"<>% into HTML entities. When ENCODE is passing a string inside another macro always use double quotes ("") type="quote". For maximum protection against cross-site scripting you are advised to install the Foswiki:Extensions.SafeWikiPlugin.
Double quotes in strings must be escaped when passed into other macros. Example:
%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'
The %ENDCODE% macro and its companion %CODE% macro are provided by the BeautifierPlugin and are used together to mark the beginning and ending of a code fragment to be beautifully displayed.
Syntax: %CODE% … %ENDCODE% or %CODE{…}% … %ENDCODE%
%CODE% … %ENDCODE% encapsulates a code fragment to be displayed using the default language syntax and CSS styling
%CODE{…}% … %ENDCODE% encapsulates a code fragment to be displayed allowing the language syntax and CSS styling to be overridden according to any parameters supplied
The Beautifier package supports many, many more language syntaxes but only the languages above have been ported to Foswiki at this point. If you need support for an additional syntax, please open an Enhancement Request to request the syntax you require.
DOM Structure: The beautified code fragment is encapsulated within a
element which, in turn, is encapulated within a
element which has two CSS class selectors, "fragment" and the language syntax identifier, which is itself encapsulated within a
element with the CSS class selector "BeautifierPlugin" as illustrated below.
language fragment">
… beautified code fragment …
Language-specific CSS styling can be applied to the beautified code fragment using CSS selectors of the form div.BeautifierPlugin div.language.fragment
Only one extended stylesheet may be supplied for a given topic using either the css="URL" macro parameter or the BEAUTIFIERPLUGIN_CSS preference setting. The final stylesheet specified is the one that will be used. If you wish to specify multiple customizations, combine all the CSS rules into a single stylesheet.
ENDCOLOR is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of shortcuts. Example:
%GREEN% green text %ENDCOLOR%
Expands to: green text
%% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write
%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
Type of the section being terminated; supported types "section", "include", "expandvariables", "templateonly".
If the STARTSECTION is named, the corresponding ENDSECTION must also be named with the same name. If the STARTSECTION specifies a type, then the corresponding ENDSECTION must also specify the same type. If the section is unnamed, ENDSECTION will match with the nearest unnamed %STARTSECTION%of the same type above it.
Twisty closure, complements the opening TWISTY tag.
Syntax: %ENDTWISTY%
Related:
ENDTWISTYTOGGLE
The Twisty closure
Syntax: %ENDTWISTYTOGGLE%
Will end the most inner unclosed Twisty Toggle section, using the proper tag
Example: %ENDTWISTYTOGGLE%
Related:
ENV{"varname"} -- inspect the value of an environment variable
Returns the current value of the environment variable in the CGI (Common Gateway Interface) environment. This is the environment that the CommandAndCGIScripts are running in.
Note: For security reasons, only those environment variables whose names match the regular expression in {AccessibleENV} in the Security Settings/Miscellaneous section of configure can be displayed. Any other variable will just be shown as an empty string, irrespective of its real value.
Example: %ENV{MOD_PERL}% displays as: not set
If an environment variable is undefined (as against being set to the empty string) it will be returned as not set.
Expands macros in expression as if they were used in the topic topictoexpandin. The viewer must have VIEW access to topictoexpandin for this to work. All the standard formatting macros can be used in expression, such as $percent and $quot.
EXPAND can be useful when you want to pick up the value of macros defined in another topic. For example, you might want to define a set of preferences in one topic, but pick up their value in another topic (this is very useful when building reusable applications). In this case you can write:
The list to be expanded into the format. Required. Currently only two types of list data are supported; topic names (type="topic") and plain strings (type="string").
If type="topic" (the default) the format string can contain any of the topic-specific format tokens specified in FormattedSearch ($web, $topic, $parent, $text, $locked, $date, $isodate, $index, $item, $rev, $username, $wikiname, $wikiusername, $createdate, $createusername, $createwikiname, $createwikiusername, $summary, $changes, $formname, $formfield, $pattern, $count, $ntopics, $nhits, $pager). In addition, the macro supports all the standard format tokens.
If type="string" then the comma separated list is treated as a list of strings. In this case, the format tokens $index and $item will return the position of the item in the list (1-based), and the item itself, respectively. Note that a comma can be embedded in the data using the standard formatting token $comma.
The FORMAT macro is currently only of use in formatting lists of topics, or of simple strings. It will be extended in future releases to add the capability to render other object types.
For more sophisticated handling of string lists, consider installing Foswiki:Extensions.FilterPlugin.
Topic where form data is located. May be of the form Web.TopicName
Current topic
format="..."
Format string. $value expands to the field value, and $name expands to the field name, $title to the field title, $form to the name of the form the field is in. The standard format tokens are also expanded.
"$value"
default="..."
Text shown if the field is defined in the topic, but the field value is empty. For example, a text field for which all the content has been deleted.
""
alttext="..."
Text shown if the field is not defined in the topic (even if it is specified in the form definition). For example, this is used when a field exists in the form definition, but the referring topic hasn't been edited since it was added.
""
rev="n"
Specifiy a revision of the topic. If not specified, defaults to the most recent rev (or the viewed rev if viewing an old rev of the same topic)
Example:
%FORMFIELD{"ProjectName"
topic="Projects.SushiProject"
default="(no project name given)"
alttext="ProjectName field not found in form"
}%
GRAY is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors. Example:
%GRAY% gray text %ENDCOLOR%
Expands to: gray text
%% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write
%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
GREEN is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors. Example:
%GREEN% green text %ENDCOLOR%
Expands to: green text
%% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write
%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
$name for groups list, $wikiusername for users list
separator
separator between items in the list
,
header
Header for the list
''
footer
Footer for the list
''
zeroresults
If set, and there are no Groups or Members that can be shown, the header and footer are suppressed, and this text is output
undefined
show
filter the output list of Groups - can be set to all, allowschange, denychange, allowschange(UserWikiName), denychange(UserWikiName)
all
expand
Set false if users should not be expanded from nested groups. Default behavior is to expand all nested groups into a flat list of users.
1
limit
If set, limits the number of results to this
infinity
limited
If limit is set, and the list is truncated, this text will be added at the end of the list
''
Note: GROUPINFO will not list members that are hidden from the current authenticated user. If the current user does not have VIEW authority for a user's topic, then the user will not be shown as a group member.
HISTORY{ attributes } -- control attributes of tables and sorting of table columns
The %HISTORY{}% macro is handled by the HistoryPlugin
Syntax: %HISTORY{ attributes }%
Argument
Description
Default value
none
Default layout: a simple list of topic revisions using the default format (see below)
"format" or format="string"
Format of one line, may include any variable which is supported by macro REVINFO
"r$rev - $date - $wikiusername"
topic="topic"
Topic name, can be in web.topic format
current topic
web="web"
Web name
current web
versions="number or range"
Number or range (format: from..to). Examples: To get version 2, write: versions="2" To get version 2 to 3, write: versions="2..3" To get version 2 to the latest, write: versions="2.." To get all versions up to version 5, write: versions="..5" To get all versions up to but not including the latest, write: versions="..-1" To get the versions from 1 to 5 in reverse order, write: versions="5..1"
all versions in the order latest to first
header="text"
Text to print before the list. May contain the tokens $next and $previous which will be evaluated if there are newer or older revisions available for the topic that are not listed according to versions (or rev1, rev2, nrev). These tokens take the syntax $next{'some text' url='url'} (the same for $previous). 'some text' is the text which should be printed, 'url' is the url for the corresponding link. The tokens $rev1, $rev2, $nrev in 'text' or 'url' will be replaced by appropriate values for the next or previous block of revisions. See the attached oopshistory.tmpl for an example of how to use this.
"$next"
footer="text"
Text to print after the list. May contain the tokens $next and $previous (see header)
"$previous"
Deprecated (but supported) parameters:
Argument
Description
Default value
nrev="number"
Number of revisions to show. Ignored if versions is specified, or if both rev1 and rev2 are specified.
10
rev2="number"
Newest revision to show
rev1+nrev if rev1 is specified, latest revision otherwise
rev1="number"
Oldest revision to show
rev2-nrev
reverse="boolean"
Show newest revisions first, if on
"on"
Additional macros
The following macros are replaced only if there is a corresponding %HISTORY% on the page. If more than one %HISTORY% is used on the same page, the values from the last one will be used.
%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
The same as %HTTP% but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.
ICON{"name" alt="" default="name"} -- small documentation graphic or icon of common attachment types
Generates a small graphic image from the set attached to DocumentGraphics. Images typically have a 16x16 pixel size. You can select a specific image by name, or you can give a full filename, in which case the type of the file will be used to select one of a collection of common file type icons.
if you specify an icon which cannot be found, the one specified in the default parameter will be used (and if that fails, the 'else' icon will be used)
Syntax: =%ICON{ "filename or icon name" [ default="filename or icon name" ] [ alt="alt text to be added to the HTML img tag" ] }%
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
ICONURL{"name" default="name"} -- URL of small documentation graphic or icon
Generates the full URL of a DocumentGraphics image, which Foswiki renders as an image. The related %ICON{"name"}% generates the full HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
ICONURLPATH{"name" default="name"} -- URL path of small documentation graphic or icon
Generates the relative URL path of a DocumentGraphics image, typically used in an HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic"
A topic in another web, i.e. %INCLUDE{"System.SiteMap"}%
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
rev="2"
Include a previous topic revision; N/A for URLs
top revision
warn="off"
Warn if topic include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name)
Any other parameter will be defined as a macro within the scope of the included topic. The example parameters on the left will result in %PARONE% and %PARTWO% being defined within the included topic.
A full qualified URL, i.e. %INCLUDE{"http://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="on"
When a page is included, normally FAIR Wiki will process it, doing the following: 1) Alter relative links to point back to originating host, 2) Remove some basic HTML tags (html, head, body, script) and finally 3) Remove newlines from HTML tags spanning multiple lines. If you prefer to include exactly what is in the source of the originating page set this to on. raw="on" is short for disableremoveheaders="on", disableremovescript="on", disableremovebody="on", disablecompresstags="on" and disablerewriteurls="on".
disabled
literal="on"
While using the raw option will indeed include the raw content, the included content will still be processed and rendered like regular topic content. To disable parsing of the included content, set the literal option to "on".
disabled
disableremoveheaders="on"
Bypass stripping headers from included HTML (everything until first tag)
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.
(a 
[[System.ProjectContributor][ProjectContributor]]
* 
Multiple 
