Macros < System

%STARTINCLUDE%
---+ Macros

_Special text strings expand on the fly to display user data or system info_

Macros are text strings in one of two forms:

<verbatim class="tml">
%MACRONAME%
%MACRONAME{ parameter="value" }%
</verbatim>

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

%TOC%

---++ Using Macros

To use a macro type its name. For example,
   * type =%<nop>T%= to get %T% (a [[%SYSTEMWEB%.PreferenceSettings][preference settings]])
   * type =%<nop>TOPIC%= to get =%TOPIC%= (a predefined [[VarTOPIC][macro]])
   * type =%<nop>CALC{ "$UPPER(Text)" }%= to get =TEXT= ([[VarCALC][CALC]] is a macro defined by [[SpreadSheetPlugin]])

*Note:*
   * To leave a macro unexpanded, precede it with an exclamation point, e.g. type =!%<nop>TOPIC%= to get =%<nop>TOPIC%=
      * Alternatively, insert a =&lt;nop&gt;= anywhere in the macro, Eg. =%&lt;nop&gt;TOPIC%=
   * Macros are expanded relative to the topic they are _used_ in, not the topic they are _defined_ in
   * Type =%<nop>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, =%<nop>UNDEFINED{default="blank"}%= will expand to =blank=.

---+++ Order of expansion
The following describes only these types of macros:
   * [[PreferenceSettings][Preference settings]]
   * Most macros provided by plugins (those that use [[PerlDoc?module=Foswiki::Func#registerTagHandler][registerTagHandler()]])
   <blockquote class="foswikiHelp">%X% *Not* those that use [[PerlDoc?module=Foswiki::Func#commonTagsHandler][commonTagsHandler()]]</blockquote>
   * Most built-in Foswiki macros
   <blockquote class="foswikiHelp">%X% Notable exceptions include: [[VarCALC][CALC]], [[VarSTARTSECTION][STARTSECTION]]/ENDSECTION, [[VarSTARTINCLUDE][STARTINCLUDE]]/STOPINCLUDE</blockquote>

%STARTSECTION{"insideoutlefttoright"}%
#StandardForm
---++++ Standard form
#InsideOutLeftToRight
The key to understanding nested expressions in Foswiki is to understand that macros are expanded "inside-out, left-to-right". *Example:*

<verbatim class="tml">
%MACRO1{
   something="%MACRO2{
      somethingelse="%MACRO3%, %MACRO4%"
   }%"
}%
</verbatim>
The macros are expanded in this order: MACRO3, MACRO4, MACRO2, MACRO1.

#AnimatedExample
---+++++ Animated Example
%JQREQUIRE{"CYCLE,EASING,CHILI"}%<!-- ids are appended with %INCLUDINGTOPIC%
to avoid duplicates in %SYSTEMWEB%.CompleteDocumentation -->%ADDTOZONE{"script"
  id="NestedSlideshow%INCLUDINGTOPIC%"
  text="<script type='text/javascript'>
jQuery(document).ready(function($) {
    $('#NestedSlideshow%INCLUDINGTOPIC%').cycle({
        fx:     'fade',
        speed:  'slow',
        timeout: 5000,
        pager:  '#NestedSlideshowNav%INCLUDINGTOPIC%',
        slideExpr: 'pre',
        pause:  true,
        pauseOnPagerHover: true
    });
});
</script>"
  requires="JQUERYPLUGIN::CYCLE"
}%%ADDTOZONE{"head"
  id="NestedSlideshow%INCLUDINGTOPIC%/css"
  text="<style type='text/css'>
    #NestedSlideshowNav%INCLUDINGTOPIC%  a { margin: 0 10px 0 0; padding: 3px 5px; border: 1px solid #ddd; background: #fff; text-decoration: none }
    #NestedSlideshowNav%INCLUDINGTOPIC%  a.activeSlide,
    #NestedSlideshowNav%INCLUDINGTOPIC%  a:hover { background: #cff }
    #NestedSlideshowNav%INCLUDINGTOPIC%  a:focus { outline: none; }
  </style>"
}%<div id="NestedSlideshowNav%INCLUDINGTOPIC%"></div>
<div id="NestedSlideshow%INCLUDINGTOPIC%">
<pre class="tml">
%<nop>INCLUDE{
    "%<nop>QUERY{
        "'%<nop>THETOPIC%'/%<nop>THEFIELD%"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %<nop>SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
</pre>
<pre class="tml">
%<nop>INCLUDE{
    "%<nop>QUERY{
        "'%<nop>SYSTEMWEB%.FAQWhatIsWikiWiki'/%<nop>THEFIELD%"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %<nop>SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
</pre>
<pre class="tml">
%<nop>INCLUDE{
    "%<nop>QUERY{
        "'%<nop>SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %<nop>SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
</pre>
<pre class="tml">
%<nop>INCLUDE{
    "%<nop>QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %<nop>SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
</pre>
<pre class="tml">
%<nop>INCLUDE{
    "%QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %<nop>SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
</pre>
<pre class="tml">
%INCLUDE{
    "%QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %<nop>SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
</pre>
<pre class="tml">
%INCLUDE{
    "%QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification
</pre>
</div>

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

%STARTSECTION{"tokensupport"}%<blockquote class="foswikiHelp">
  %T% When working with a given [[Macros][macro]], consult its documentation to determine which parameters support the =$percent/$percnt= [[FormatTokens][format tokens]]. Generally only _output parameters_ like =header=, =format= and =footer= support [[FormatTokens][format tokens]].
  </blockquote>%ENDSECTION{"tokensupport"}%
*Example:*
<verbatim class="tml">
%MACRO1{
   format="$percentMACRO2{
      format=\"%MACRO3%, %MACRO4%\"
   }$percent"
}%
</verbatim>
The macros are expanded in this order: MACRO3, MACRO4, MACRO1, *MACRO2*.
#AnimatedDelayedExample
---+++++ Animated Example
From the [[FormattedSearch#ConditionalOutputExample][conditional output example]]:

%JQREQUIRE{"CYCLE,EASING,CHILI"}%<!-- ids are appended with %INCLUDINGTOPIC%
to avoid duplicates in %SYSTEMWEB%.CompleteDocumentation -->%ADDTOZONE{"script"
  id="DelayedSlideshow%INCLUDINGTOPIC%"
  text="<script type='text/javascript'>
jQuery(document).ready(function($) {
    $('#DelayedSlideshow%INCLUDINGTOPIC%').cycle({
        fx:     'fade',
        speed:  'slow',
        timeout: 5000,
        pager:  '#DelayedSlideshowNav%INCLUDINGTOPIC%',
        slideExpr: 'pre',
        pause:  true,
        pauseOnPagerHover: true
    });
});
</script>"
  requires="JQUERYPLUGIN::CYCLE"
}%%ADDTOZONE{"head"
  id="DelayedSlideshow%INCLUDINGTOPIC%/css"
  text="<style type='text/css'>
    #DelayedSlideshowNav%INCLUDINGTOPIC%  a { margin: 0 10px 0 0; padding: 3px 5px; border: 1px solid #ddd; background: #fff; text-decoration: none }
    #DelayedSlideshowNav%INCLUDINGTOPIC%  a.activeSlide,
    #DelayedSlideshowNav%INCLUDINGTOPIC%  a:hover { background: #cff }
    #DelayedSlideshowNav%INCLUDINGTOPIC%  a:focus { outline: none; }
  </style>"
}%<div id="DelayedSlideshowNav%INCLUDINGTOPIC%"></div>
<div id="DelayedSlideshow%INCLUDINGTOPIC%">
<verbatim class="tml">
%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
</verbatim>
<pre class="tml">
%<nop>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
</pre>
<pre class="tml">
%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percent<nop>ICON{
    \"$percent<nop>IF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
</pre>
<pre class="tml">
%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percent<nop>ICON{
    \"$percentIF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
</pre>
<pre class="tml">
%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * &lt;img src=\"$percentICONURL{
    \"$percentIF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent\"/&gt; [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
</pre>
</div>
%ENDSECTION{"insideoutlefttoright"}%

See also: [[FormattedSearch#NestedSearchExample][FormattedSearch]]

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

By convention all settings, predefined macros and macros registered by plugins are always UPPER-CASE.
<!--
   * Set CONDITIONS = According to [[%BASETOPIC%]], The %WHAT% is %STATE% today. (Set in [[Macros]]).
   * Set WEATHER = It's %DEFAULT{default="raining"}%.
-->
%INCLUDE{"PreferenceSettings"}%

#PreDef
---++ 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 =%<nop>SEARCH%=, are powerful and general tools.

<blockquote class="foswikiHelp">
%X% Predefined macros can be overridden by [[%SYSTEMWEB%.PreferenceSettings][preference settings]] (except TOPIC and WEB)

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

%T% *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 =%<nop>BASETOPIC%=, =%<nop>INCLUDE%=, and the mighty =%<nop>SEARCH%=.
</blockquote>

Your installation of Foswiki %WIKIVERSION% has the following registered macros:

%SEARCH{
    "^Var[A-Z_0-9]+$"
    casesensitive="on"
    web="%SYSTEMWEB%"
    type="regex"
    scope="topic"
    format="$percentINCLUDE{$web.$topic}$percent"
    nonoise="on"
}%

---+++ Shortcuts

The following macros are [[%SYSTEMWEB%.PreferenceSettings][preference settings]] and are frequently used in topic content.
   * =%<nop>BR%= - line break
   * =%<nop>BULLET%= - bullet sign
   * =%<nop>BB%= - line break and bullet combined
   * =%<nop>BB2%= - indented line break and bullet
   * =%<nop>RED% text %<nop>ENDCOLOR%= - colored text (also =%<nop>YELLOW%=, =%<nop>ORANGE%=, =%<nop>PINK%=, =%<nop>PURPLE%=, =%<nop>TEAL%=, =%<nop>NAVY%=, =%<nop>BLUE%=, =%<nop>AQUA%=, =%<nop>LIME%=, =%<nop>GREEN%=, =%<nop>OLIVE%=, =%<nop>MAROON%=, =%<nop>BROWN%=, =%<nop>BLACK%=, =%<nop>GRAY%=, =%<nop>SILVER%=, =%<nop>WHITE%=)
   * =%<nop>H%= - %H% Help icon
   * =%<nop>I%= - %I% Idea icon
   * =%<nop>M%= - %M% Moved to icon
   * =%<nop>N%= - %N% New icon
   * =%<nop>P%= - %P% Refactor icon
   * =%<nop>Q%= - %Q% Question icon
   * =%<nop>S%= - %S% Red star icon
   * =%<nop>T%= - %T% Tip icon
   * =%<nop>U%= - %U% Updated icon
   * =%<nop>X%= - %X% Alert icon
   * =%<nop>Y%= - %Y% Done icon

See ShortcutMacros for a full list of predefined shortcuts.

%STOPINCLUDE%

---
*Related Topics:* UserDocumentationCategory
<!-- %JQREQUIRE{"chili"}% -->
This topic: System > WebHome > Macros
Topic revision: 08 Oct 2011, ProjectContributor (raw view)
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback