Macros

A macro is a block of text that can be executed after it's defined. Essentially it is a mini template defined inside the template file.

This allows things like repeating the same block of text without retyping it. The real power of macros is that they can accept parameters and even be passed blocks of text very easily; all of which is described below. Also to keep in mind is that the template file itself can be executed like a macro from another macro using the include output command.

Basic

Defining a macro in Stencil is done with this simple syntax

	$macro myMacro () {
		My Macro!
	};
	

	$myMacro ();
	

	My Macro!
	

Parameters

Parameters are specified in familiar parentheses format. Remember, Stencil is an untyped language so no types are specified, just names.

	$macro myMacro ( greeting, name ) {
		$greeting; $name;!
	};
	

	$myMacro('Hello','World');
	

	Hello World!
	

Parameters can be passed by location (as in the previous example) or by name. You must choose one passing method or the other. You cannot mix methods.

	$macro myMacro ( greeting, name ) {
		$greeting; $name;!
	};
	

$myMacro(greeting='Hello',name='World');
	

	Hello World!
	

Default Values

Parameters can also have default values. You simply specify an expression after the parameter name. Any parameters not passed will receive their default value or null if no default was defined.

	$macro myMacro ( greeting='Hello', name ) {
		$greeting; $name;!
	};
	

	$myMacro(name='World');
	

	Hello World!
	

Any Parameters

Occasionally you would like to accept any number of parameters and process them all in your macro. This is done by marking a parameter with the '*' sign. Then you can enumerate the parameter keys/values at will.

	$macro myMacro (*all) {
		$foreach entry in all {
			$entry.key = $entry.value;
		};
	};
	

$myMacro(one='blue',two='red',three='green');
	

	one = blue;
	two = red;
	three = green;
	

Blocks

Macros can also accept named blocks. Square brackets after the parameter declaration list allow you to declare the names of blocks the macro can take.

	$macro myMacro ( greeting, name ) [ header, footer ] {
		$headerBlock;
		
		$greeting; $name;
		
		$footerBlock;
	};
	

Blocks are passed to the macro by simply naming blocks of text after you call the macro.

	$myMacro ('Hello', 'World')
		header {
			<div>
		}
		footer {
			<div>
		};
	

	<div>
	Hello World!
	</div>
	

Unnamed Block

In some cases, like when a macro needs to only accept a single macro, you can skip name when passing the block. In the block declaration list you specify what name to give the block with the '+' sign.

	$macro myMacro ( greeting, name ) [ +block ] {

		$greeting; $name;
		
		$block;		
	};
	

	$myMacro ('Hello', 'World') {
		Some Extra Text
	};
	

	Hello World!
	
	Some Extra Text
	

Double Blocks

In certain cases, like when outputting Javascript or CSS, the block syntax using curly braces can get in the way. Although you can escape a curly brace with the '\{' sequence it would still be troublesome to work that way. Thus Stencil supports 'Double Blocks'.

Double Blocks use ' to open and ' to close. Thus allowing the use of '{' and '}' without translation. Also inside a double block you can use '$$' to begin dynamic outputs.

		<style>
			$raw {{
				h3 {
					color: #fff;
				}
				div {
					color: $$divColor;
				}
			}}
		</style>
	

Block Modes

Sometimes just replacing the value in a block is too trivial. A macro can provide default text for a block. When passing a block you can specify how that default text is handled with the following modes:

• before
• after
• replace

	$macro myMacro () [ pleading ] {
		Modes are neat...
		$pleading {
			Don't replace me!
		};
	};
	

	$myMacro ()
		after pleading {
			Some Extra Text
		};
	

	Modes are neat...
	Don't replace me!
	Some Extra Text