The Page Header and Page Footer

The page header is a feature that lets you prefix the HTML prologue onto the page, after the page’s body has been inserted into the template and macros have been processed.

You can prefix any page header you like, or you can accept RubyFrontier’s default page header. The default page header is quite powerful and complete, and in many cases will be all you need. In any event, it is a good model for your own page header. So I’ll start by describing the default page header; then I’ll talk about how to supply your own page header instead.

The Default Page Header

To get the default page header, start your template with a macro that says:

    <%= pageheader() %>

(The default template, which is identical to the “white” template in user/templates, does start this way.)

The result of that call is that following page header will be prefixed to your page:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
    <%= metatags() %>
    <%= linkstylesheets() %>
    <%= linkjavascripts() %>
    <title><%= title %></title>
    </head>
    <%= bodytag() %>

But before the prefixing takes place, the macros within that page header are themselves processed. These are standard macros — that is, they are calls to stock methods included within RubyFrontier itself. Let’s walk through the default page header, and I’ll comment on each of its parts.

The DOCTYPE is XHTML. In general, RubyFrontier leans towards XHTML, and if possible you should probably use it. (If you really want a different DOCTYPE, you’ll need to supply your own page header, as described later on this page.)
The <head> area begins. The metatags() call inserts tags at the start of the <head> area, as follows:
- If the scalar directive :metacharset is true, a character set <meta> tag is inserted, in accordance with the value of the :charset scalar directive. The default is that :metacharset is true, and :charset is "utf-8". For example:
```
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
```
- If the scalar directive :includemetagenerator is true (the default), a generator <meta> tag is inserted with the value "RubyFrontier". For example:
```
    <meta name="generator" content="RubyFrontier" />
```
- If there are any scalar directives whose name is of the form metaxxx, a tag of the form <meta name="xxx" content="yyy"> is inserted, where xxx is whatever occurs after meta in the directive’s name, and yyy is the directive’s value. For example:
```
    #metakeywords "RubyFrontier, coolness"
```
  would result in:
```
    <meta name="keywords" content="RubyFrontier, coolness" />
```
- If there are any scalar directives whose name is of the form metaequivxxx, a tag of the form <meta http-equiv="xxx" content="yyy"> is inserted, where xxx is whatever occurs after meta in the directive’s name, and yyy is the directive’s value. For example:
```
    #metaequivrobots "noindex"
```
  would result in:
```
    <meta name="robots" content="noindex" /> 
```
- If there is a scalar directive whose name is :meta, its value is inserted as a tag without alteration. The intention here is to give you a chance to place other miscellaneous material into the document’s <head> area.
The linkstylesheets() call writes stylesheet files to disk and inserts links to them. (Also, it can embed a stylesheet.) For a discussion of how you tell this macro what stylesheet files to link to or embed, see the discussion of stylesheets.
The linkjavascripts() call writes javascript files to disk and inserts links to them. (Also, it can embed a script.) For a discussion of how you tell this macro what javascript files to link to or embed, see the discussion of JavaScript.
The value of the :title directive is inserted as the <title> tag, and the <head> area comes to an end.
The bodytag() call generates the opening <body> tag. A number of standard attributes can be inserted into this <body> tag by supplying them as scalar directives:
- :background. The name (with no extension) of a file in an #images folder.
- :bgcolor, :text, :link, :alink, :vlink. A color string; if hex, you may omit the initial “#”.
- :topmargin, :leftmargin, :marginheight, :marginwidth.
- :onload, :onunload.

Supplying Your Own Page Header

Instead of merely calling pageheader() to get the default page header, you can supply your own page header. A common strategy is to start with the default page header and modify it slightly, taking advantage more or less of all the same macros.

There are two ways to supply your own pageheader:

Supply a #pageheader.txt directive object. It should be a text file. The contents of the text file are used as the page header, and any macros in it are processed.
Supply a #pageheader directive. It should be a Pathname pointing to a text file. The contents of the text file are used as the page header, and any macros in it are processed.

If you supply a #pageheader.txt directive object, you can override it in an individual page or lower-level folder with a #pageheader directive whose value is false, thus causing the pageheader() macro call in your template to result in the default template.

Prefixing, Not Substitution

No matter how you supply the page header, and whether or not you use the default page header, RubyFrontier always does the same thing. Having obtained the text of the page header, and having processed any macros within it, RubyFrontier simply jams the resulting text onto the front of the Web page as rendered thus far.

(Thus, the ironical truth is that your template does not really have to start with a pageheader() call in order for you to obtain the default page header. The pageheader() call can actually appear anywhere. It does not mean, “Substitute the default page header at this point;” it just means, “I want to use the default page header when the time comes to jam a page header on the front of the page.”)

The Page Footer

The pagefooter() macro is similar to pageheader(), but much simpler. It generates the closing </body> and </html> tags, but it does not actually substitute them for the call. Instead, it stores them as :pagefooter in the page table, and then, after the page header has been jammed onto the front of the rendered page, this value is jammed onto the end of the rendered page.

Thus, your template does not have to end with a pagefooter() call; the call can actually appear anywhere. And, instead of a pagefooter() call, you can do anything you like that causes a :pagefooter key-value pair to appear in the page table (such as using a directive); as long as such a value exists at the right time in the page-building process, it will be jammed onto the end of the rendered page.