%META:TOPICINFO{author="ProjectContributor" date="1655468868" format="1.1" version="1"}%
%META:TOPICPARENT{name="Macros"}%
---+ FORMAT -- format a list of objects
---++ Parameters
     %TABLE{sort="off"}%
     | *Parameter* | *Description* | *Default* |
     | ="one, two, three"= | 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"=). | |
     | =format= | Format string; see [[%TOPIC%#FormatFormattingTokens][Supported formatting tokens]] for possible values. | |
     | =header= | Text to come before the formatted output | |
     | =footer= | Text to come after the formatted output | |
     | =separator= | Separator between formatted elements | =$n= |
     | =type= | Treat input list as either =topic= or =string= | =topic= |
---++ Examples
   <verbatim class="tml">
   %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="
   }%</verbatim>
---++ Supported formatting tokens
If =type="topic"= (the default) the format string can contain _any_ of the
topic-specific format tokens
specified in FormattedSearch (=$web=, =$topic=, =$parent=, =$text=, =$locked=,
=$date=, =$isodate=, =$index=, =$item=, =$rev=, =$username=, =$wikiname=, =$wikiusername=,
=$createdate=, =$createusername=, =$createwikiname=, =$createwikiusername=,
=$summary=, =$changes=, =$formname=, =$formfield=, =$pattern=, =$count=,
=$ntopics=, =$nhits=, =$pager=).
In addition, the macro supports all the standard [[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.

<div class="foswikiHelp">%I% For more sophisticated handling of string lists, consider installing Foswiki:Extensions.FilterPlugin </div>

%STOPINCLUDE%
---++ Related
 [[VarSEARCH][SEARCH]], [[VarENCODE][ENCODE]], FormattedSearch
