The <al-macro> tag is used to define a macro. All enclosed content becomes part of the macro definition.
Executing the macro registers the macro with the execution context via the register_macro() method using the name in the name (5.4.1.1) attribute.
Note that the execution of the macro content is deferred until later when the macro is expanded via the <al-expand> (5.4.3) tag. This means that executing a macro definition produces no output. Output is produced only when the macro is expanded.
>>> import albatross
>>> ctx = albatross.SimpleContext('.')
>>> albatross.Template(ctx, '<magic>', '''
... <al-macro name="noargs">
... Will be executed when macro is expanded.
... </al-macro>
... ''').to_html(ctx)
>>> ctx.flush_content()
>>> albatross.Template(ctx, '<magic>', '''
... <al-expand name="noargs"/>
... ''').to_html(ctx)
>>> ctx.flush_content()
Will be executed when macro is expanded.
The deferred execution also means that you can include content that only works within the context of the <al-expand> tag.
>>> import albatross
>>> ctx = albatross.SimpleContext('.')
>>> albatross.Template(ctx, '<magic>', '''
... <al-macro name="oops">
... <al-value expr="oops">
... </al-macro>
... ''').to_html(ctx)
>>> ctx.flush_content()
>>> templ = albatross.Template(ctx, '<magic>', '''
... <al-expand name="oops"/>
... ''')
>>> try:
... templ.to_html(ctx)
... ctx.flush_content()
... except NameError, e:
... print e
...
name 'oops' is not defined
>>> ctx.locals.oops = 'there is now'
>>> templ.to_html(ctx)
>>> ctx.flush_content()
there is now
In the above example the content of the macro makes reference to a oops that is not defined in the execution context when the macro was defined.
Inside a macro definition you can use as yet undefined macros.
>>> import albatross
>>> ctx = albatross.SimpleContext('.')
>>> albatross.Template(ctx, '<magic>', '''
... <al-macro name="bold-red">
... <font color="red">more <al-expand name="bold"><al-usearg></al-expand> please</font>
... <font color="red"><al-expand name="bold">more <al-usearg> please</al-expand></font>
... </al-macro>
...
... <al-macro name="bold">
... <b><al-usearg></b></al-macro>
... ''').to_html(ctx)
>>> ctx.flush_content()
>>> albatross.Template(ctx, '<magic>', '''
... <al-expand name="bold-red">spam</al-expand>
... ''').to_html(ctx)
>>> ctx.flush_content()
<font color="red">more <b>spam</b> please</font>
<font color="red"><b>more spam please</b></font>
Care must by taken to ensure that you do not make circular macro references else you will cause a stack overflow.