Standard Macros and Other Convenience Methods

RubyFrontier includes a number of convenience methods, to be called as needed during macros to assist with common tasks.

NOTE: Where these methods are located in RubyFrontier’s code, and how they are called, depends in part upon how Frontier did these things (since I wanted to make my own transition from Frontier to RubyFrontier as easy as possible). Not all Frontier convenience methods have been provided, and RubyFrontier does some things differently from Frontier. But this could all evolve further in future, and meanwhile, since this is Ruby, it’s very easy to add your own methods and inject them into the relevant classes (the user.rb file is a good place to do this).

The macros are shown as they might be called in a macro under the rules of macro scoping.

Typically used in the template

• pageheader(). Asks for the default page header. If used, usually appears at the start of the template (but can actually appear anywhere).

• pagefooter(). Generates the default page footer, which consists solely of the closing </body> and </html> tags. Usually appears at the end of the template (but can actually appear anywhere).

• html.getNextPrev(). Returns identifiers for the next and previous pages, good for forming navigation links. For further discussion, see here.

Typically used in the page header

• metatags(), linkstylesheets(), linkjavascripts(), bodytag(). See on the default page header for full discussion.

• linkjavascript(). Called by linkjavascripts(). Takes one parameter, the simple name of the javascript file. Finds that javascript file (in a #javascripts folder), copies it out to disk, and returns a link to it from the page currently being rendered.

• embedjavascript(). Called by linkjavascripts(). Takes one parameter, the simple name of the javascript file. Finds that javascript file (in a #javascripts folder) and returns its text, wrapped up in a proper <script> tag.

• linkstylesheet(). Called by linkstylesheets(). Takes one parameter, the simple name of the stylesheet file. Finds that stylesheet file (in a #stylesheets folder), copies it out to disk, and returns a link to it from the page currently being rendered.

• embedstylesheet(). Called by linkstylesheets(). Takes one parameter, the simple name of the stylesheet file. Finds that stylesheet file (in a #stylesheets folder) and returns its text, wrapped up in a proper <style> tag.

Typically used in the page body (or template) or macros

• imageref(). Writes an image to disk and returns an <img> tag referring to it. See on images for full discussion.

• makexref() and xref(). Used for forming cross-references and auto-numbering.

• html.getOneDirective(). Takes two parameters, a symbol name of a directive (such as :title) and a Pathname pointing to a page object. Alternatively, the first parameter may be an array of names of directives. Alternatively, the second parameter may be a page identifier that can be looked up in the autoglossary. Reads the page object (only if it is a .txt or an .opml file) and extracts and returns the value of the scalar directive at its start with the specified name(s) (or nil).

• html.getTitleAndPaths(). Given a single parameter, uses that parameter as a key into the autoglossary to retrieve information about a page of the site, and returns an array of the three values it finds there: the page’s title (as a string), its pathname (as a Pathname object), and the page object’s pathname (as a Pathname object). Any of those can be nil. There’s nothing here you couldn’t do yourself by look into the autoglossary hash; it’s just a quick shortcut. Useful, for example, when what you have is a page object’s simple name and you want to form a link to it whose text includes the title of the Web page the page object generates; or when you have a page identifier and you need the pathname of the actual page object. (Note: if you were previously calling html.getTitleAndPath(), no problem; it remains as legacy code.)

• html.getLink(). An expanded version of Frontier’s utility for creating a complete <a> tag, replacing both Frontier’s html.getLink() and my own well-known glossSub() macro. Takes two required parameters, the “linetext” (the text surrounded by the tag) and the URL for the href attribute value. A third parameter is an optional hash of symbol–string pairs, which are turned into additional attributes of the <a> tag, except that two symbols are treated specially: :anchor is affixed to the end of the URL (with "#" if needed), and :othersite is prefixed to the start of the URL with "^", for use by our autoglossary external site mechanism (see “Links to Other RubyFrontier Sites” on this page).

• html.pagesInFolder(). Given a folder, lists all the renderable page objects in that folder. The list is an array of identifiers suitable as keys into the autoglossary. The order is the order from the folder’s #nextprevs.txt file if there is one; otherwise it’s alphabetical.