Chapter 4. Templating System and page construction: Pages and Styles

Elements

Pages and Styles form hierarchical tree structures where each node can have additional children named Elements. This is illustrated in Figure 4-1.

The corresponding database tables are shown in Figure 4-2. Notice that a Host has an associated root Page and default Style, and that Styles may be associated to Pages.

Page and Style Elements are the building blocks of Midgard's templating system. They have a name and a value. Their value field contains text which may include other Elements: the syntax for embedding an Element into another one within html is <[name]> [1]

Page Elements are meant for scripting while Style Elements are meant for layout. In practice you can mix script and markup code in either of the Elements.

Inheritance

Child Elements override parent Elements that share the same name. The only difference between Page and Style Elements is in this inheritance mechanism:

• Style Elements are always inherited, unlike Page Elements which may be marked as inheritable.

• Page Elements override Style Elements.

This is best illustrated with a description of the Elements gathering process which builds on Example 3-1. See Figure 4-3.

When a matching Host is found, Midgard tokenizes the trailing part of the URL, which is everything after the Host name and possibly the prefix. So, going back to Example 3-1, the host is http://foo.org/foo/, and has an associated root Page (whose name doesn't show up in the URL).

Midgard then procedes by walking the Page tree and gathering inheritable Page Elements. This process continues as long as it finds matches. It stores the contents of the value field of the Elements in an Apache name-value array. When a Page Element has the same name as a previously encountered Page Element, the most recent one overrides the previous one. So <[1]> and <[2]> have been gathered from the Geeks Page, and <[1]> from the Functions Page has overriden the previous one.

The process of walking down the Page tree eventually ends when encountering a leaf Page where the remaining tokens don't match a child Page. In our example, Functions is the Page that will be built.

Each Page has a Style attached to it, either explicitly thanks to the style field, inherited from a parent Page, or the default style for the Host. Having walked down the Page tree, mod_midgard begins the process of walking up the Style tree to gather Style Elements, starting from the Style attached to the leaf Page. Child Style Elements are stored in the Apache name-value array, unless their name has already been attributed to a Page Element, or former Style Element.

Functions is explicitly attached to Style 2. So <[3]> and <[4]> become available from Style 2 and Style 1 respectively.

<[5]> is an empty Element since it hasn't been defined as a child of any of the available tree nodes.

Page construction, midgard-root.php4

At this point, what we have is an Apache name-value array with all the Elements that have been gathered during the Page tree walk-down and Style tree walk-up process. Midgard will then start processing the midgard-root.php4 file.

<?
$midgard = mgd_get_midgard();
$argc = $midgard->argc;
$argv = $midgard->argv;
?>
<[code-compat]>
<[code-global]>
<[code-init]>
<[ROOT]>

mgd_get_midgard()() is the entry point to the Midgard system. See Chapter 52 for more information about the $midgard object. What we are interested in are the four Elements which get processed at that time.

<[ROOT]> references other Elements which may in turn reference others and so on. Each referenced Element is replaced by its content until they have all been expanded. <[ROOT]> is the entry point for the replacement of Elements with their value.

The usefulness of the other three Elements is in their being called before any data is sent back to the browser. This means that you can set additional HTTP headers, or set variables used by your Page Elements there. They can be used for anything, but the convention has been to use them in the following way:

• <[code-compat]> can be used to define functions you deem obsolete but are still in use by parts of your site, for backwards compatibility code, for migration between different Midgard version, etc...

• <[code-global]> is an Element where library-type code can be defined or imported for the rest of the Page and Style Elements to use, for functionality you want in every Page.

• <[code-init]> can be used for code specific to a particular Page. It is very often used for handling arguments sent to a virtual path enabled Page.

Predefined Elements

<[title]> and <[content]> are defined in the Page being built. They are not database records, but database fields.

A typical example

You will usually need a <[ROOT]> style element similar to the one in Example 4-1.

<html>
  <head>
    <title><[title]></title>
  </head>
  <body>
    <table width="100%">
      <tr height="200"><td height="200">
        <[menu]>
      </td></tr><tr><td>
        <[content]>
      </td></tr>
    </table>
  </body>
</html>

You'll have to define a <[menu]> Element, but <[title]> and <[content]> will be taken from the built Page.