Midgard Templating Engine
Elements
Pages and Styles form hierarchical tree structures where each node can have additional children named Elements.
Each Midgard website has an associated root Page and default Style. In addition, Styles may be associated to Pages overriding the host default style.
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 or XML output is <(name)>.
Generally, 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:
When a matching website is found, Midgard tokenizes the trailing part of the URL, which is everything after the Host name and possibly the prefix. So for example the host is http://foo.org/foo/, and has an associated root Page.
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, midgard-apache 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.php
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 file midgard-root.php:
<(code-compat)>
<(code-global)>
<(code-init)>
<(ROOT)>
<(code-finish)>
What we are interested in are the five 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 in the style for the replacement of Elements with their value.
The usefulness of the three code- 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. For example, MidCOM execution is started here.
<(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. For example, MidCOM calls the request handlers of components here.
There is also the element <(code-finish)> which is called after regular output from <(content)> is finished. This can be used for example with output buffering in MidCOM's cache engine.
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 this one:
<html>
<head>
<title><(title)></title>
</head>
<body>
| <(menu)> |
| <(content)> |
</body>
</html>
You'll have to define a <(menu)> Element, but <(title)> and <(content)> will be taken from the current Page.
The MidCOM template provides several other useful style elements including <(edit-this-page)>, <(breadcrumb)> and <(navi)>.