Macro parameters

Macros can define parameters and use those values to build contents and make decisions. Here is a simple example:

<macro name="hello" parameters="name">
	Hello <n.name/>.
</macro>

Note that the value of the parameter is printed with the <n.name/> call (line 2 above). The parameters attribute of the macro tag is a comma-separated list of names. So we can add more parameters if needed:

<macro name="hello" parameters="name, city">
	Hello <n.name/>. Welcome to <n.city/>.
</macro>

Calling a macro like that is quite simple. Here you can find some examples and variations:

<!-- Example 1 -->
<n.hello name="Mike" city="San Francisco"/>

<!-- Example 2 -->
<n.hello>
	<name>Mike</name>
	<city>San Francisco</city>
</n.hello>

<!-- Example 3 -->
<n.hello name="Mike">
	<city>San Francisco</city>
</n.hello>

Preventing Errors

Macros should only print the value of a parameter if it was really provided, otherwise the page will display an error message (Error 500 – null written to stream). To prevent such errors, you should check if the parameter is available with an if-statement like this:

<macro name="hello" parameters="name, city">
	<!-- If "name" is available-->
	<n.if.not.is_null.name>
		<then>
			Hello <n.name/>.
		</then>
	</n.if.not.is_null.name>

	<!-- If "city" is available-->
	<n.if.not.is_null.city>
		<then>
			Welcome to <n.city/>.
		</then>
	</n.if.not.is_null.city>
</macro>

In this case, both parameters become optional and you can call the macro with or without them:

<n.hello/>
<n.hello name="Mike"/>
<n.hello city="San Francisco"/>
<n.hello name="Mike" city="San Francisco"/>

The Dot Parameter

The dot parameter is a special parameter that allows you to pass a block to the macro. Here is a simple example:

<macro name="blue" dot_parameter="contents">
	<div style="color:blue">
		<n.contents/>
	</div>
</macro>

This macro wraps the value of the contents parameter with a DIV element that has blue text. The first thing you should note is that the dot parameter is a normal parameter, so you can call the macro as explained earlier:

<n.blue contents="This is a blue text"/>

But the main advantage of the dot parameter is that you can call the macro and place the value of the dot parameter between the opening and closing tags of the macro call:

<!-- Example 1 -->
<n.blue.>This is a blue text</n.blue.>

<!-- Example 2 -->
<n.blue.>
	This is a full sentence <br/>
	with <b>bold</b> and <i>italic</i> text. <br/>
	This is the last line.
</n.blue.>

In the second example, we pass a complex set of HTML elements as the value of the contents parameter. Note also that the macro call ends with a dot ("."), which is the reason why we call it the "dot" parameter.

If you want, you can mix the dot parameter with other parameters:

<!-- Creates the macro with two parameters -->
<macro name="blue" dot_parameter="contents" parameters="header, footer">
	<div style="color:red">
		<n.header/>
	</div>
	<div style="color:blue">
		<n.contents/>
	</div>
	<div style="color:green">
		<n.footer/>
	</div>
</macro>

<!-- Example 1 -->
<n.blue. title="Red Header" contents="This is a blue text" footer="Green Footer"/>

<!-- Example 2 -->
<n.blue. title="Red Header" footer="Green Footer">
	This is a blue text
</n.blue.>