RubyFrontier Documentation

Macros and Macro Scoping

A macro is an ERB expression in your page object or template. ERB is called to process the page after the page object has been poured into the template (unless you specify that the :processmacros scalar directive is false, which would be a very unusual thing to do).

If you don’t know about ERB, you should study it in order to understand the syntax. Basically, a typical macro expression in a page object looks like this:

    <%= imageref("myimage") %>

The thing to notice there is the equal-sign. That means that the result of evaluating the contents of the expression will be substituted for the expression. If the equal-sign were not there, the contents of the expression would be evaluated, with any side effects, but there would be no substitution; the expression is simply deleted from the output.

Macros are evaluated under a special set of evaluation rules called macro scoping. (Also, outline renderers are run under macro scoping.) You will want to understand macro scoping in order to write your own macros (plus tools, plus outline renderers, etc.).

Macro Scoping

In Frontier, when a macro runs, certain abbreviated modes of expression are enabled. This is mostly just a way of making things easier on the programmer writing the macro. For compatibility, RubyFrontier provides a similar mechanism. Linguistically, underneath the hood, the implementation is performed very differently: Frontier uses the dreaded with, whereas RubyFrontier, being Ruby, uses bindings, method_missing, introspection, and a lot of other cool stuff. But you don’t need to worry about that. You just need to know the rules for these abbreviated modes of expression. So here they are.

Note that you can add your own methods to the repertory of things that can be accessed via macro scoping, by defining them in a user.rb file. For example, user.rb could define a standard macro as an instance method of UserLand::Html::StandardMacros, and a macro could then call it directly by name. Or, user.rb could define a PageMaker method as an instance method of UserLand::Html::PageMaker, and a macro could then call it as a method of html.

Next: The Autoglossary

This documentation prepared by Matt Neuburg, phd = matt at tidbits dot com (, using RubyFrontier.
Download RubyFrontier from GitHub.