{macro}
A template function: declared parameters, given in order or by name, read as fields inside its body.
Syntax
{macro 'name', required, optional='default'} ... {$required} {$optional} ... {/macro}
{name 'value'}
{name 'value', 'other'}
{name required='value', optional=$x}
{name 'value'} content for @content@ {/name}
{macro:name ...}Parameters
-
name -
The name of the macro, used as a tag from here on. Under the strict check it may not be a built-in tag, an application tag or a
{define}already. -
parameters -
The items after the name declare the macro's parameters: a name alone is required,
name=defaultis optional - the default is evaluated where the macro is used. A parameter may not be named like an option every tag takes (sort,first,content...).
Description
{macro 'entry', label, type='text'} ... {/macro} declares a tag {entry} with two parameters. Defining prints nothing; each use renders the body once, with the values of that use as the fields of the macro's one row: {$label}, {$type}.
A use gives values in their declared order ({entry 'E-mail', 'email'}), by name ({entry label='Name'}), or both. A parameter written alone in the declaration is required; one with =default fills in when the use leaves it out, its default evaluated at the use. Inside the body the fields round the use stay visible behind the parameters, so a macro used inside a loop can read the row as well.
A pair use hands its content to @content@, and {slot}s work as in a {define}. The content renders in the body, on the macro's one row, so there too a parameter stands in front of a field of the same name round the use: in {rows}{entry 'x'}{$label}{/entry}{/rows} the {$label} is the parameter, {$label@rows} the row's own. A macro can call itself. A value given to a macro is text, never template, as every value is. {macro:entry} asserts that the name is a macro.
Under the strict check a required parameter left out, more values than parameters, a named parameter the macro does not declare, and a parameter named like an option every tag takes are errors. The difference with {define}: a define reads its parameters as {#name} like a custom tag file, a macro declares them and reads them as fields.
Examples
A form field, three ways
Values given in order, by name, or left to the default.
{macro 'macroEntry', label, kind='text', value=''}
<p><label>{$label} <input type="{$kind}" name="{$label}" value="{$value}"></label></p>
{/macro}
{macroEntry 'E-mail', 'email'}
{macroEntry label='Name', value='Ada'}
{macroEntry 'City'}
Used inside a loop
The macro's own parameters are its fields, and the row round the use stays visible behind them.
{macro 'macroPrice', amount}
<li>{$product}: € {$amount | number_format(@, 2)}</li>
{/macro}
<ul>
{macroProducts}
{macroPrice $price}
{/macroProducts}
</ul><?php
$macroProducts = [
[ 'product' => 'Kettle', 'price' => 39.5 ],
[ 'product' => 'Toaster', 'price' => 24 ],
[ 'product' => 'Blender', 'price' => 79.9 ] ];
?>- Kettle: € 39.50
- Toaster: € 24.00
- Blender: € 79.90
A pair use and @content@
The content of a pair use goes where the body has @content@.
{macro 'macroBox', heading}
<section style="border-left:3px solid #2a6fd6; padding:2px 12px; margin:6px 0">
<strong>{$heading}</strong>
<div>@content@</div>
</section>
{/macro}
{macroBox 'Tip'}Press <kbd>/</kbd> to search.{/macroBox}
{macroBox heading='Note'}Prices include VAT.{/macroBox}A required parameter left out
Under the strict check this is an error naming the macro and the parameter.
{macro 'entry', label, kind='text'}
<label>{$label} <input type="{$kind}"></label>
{/macro}
{entry kind='email'} the required label is missing - an error
{entry 'Name', 'text', 'x'} one value too many - an error
{entry 'Name', size=20} size is not a parameter of entry - an errorSee also
- {define} Writes a custom tag in the template itself - what a _tags/name.pad file is, without the file.
- {parms} Declares the parameters of a custom tag, with defaults, at the top of its template.
- {slot} A named place in a custom tag's template - and the fill a caller gives it.
- {set} Assigns one or more variables, as globals that outlive the level the tag stands in.