Fork me on GitHub

include

An article by Gaspard Bucher

Include another template or some ancestor (recursion).

Include another template or some ancestor (recursion).

  • template Just the ‘template_name’ to include a template from the same skin, ’/skin_name/template_name’ to include from another skin, or ’$brick_name-skin_name/template_name’ to include a template from a filesystem skin.
  • part only include a specific part of the specified template
  • depth maximal recursion depth for recursive includes (default ?, max. 30)
see name

For properly including references to assets into your templates see the correponding section in html to zafu.

The include tag has two different roles: pre-processing and recursion. But before diving into these two uses, there are some things to know about template paths.

A note on the template paths

When referring to another template, the path can be either relative, absolute or filesystem absolute (refers to a filesystem skin). Here are the different syntaxes:

Relative path:
<r:include template='Section'/>

Absolute (first name is the skin)
<r:include template='/mojo/base/Section'/>

Filesystem absolute (first name is the brick-skin)
<r:include template='$mybrick-myskin/base/Section'/>

Pre-processing

You can include sub-templates inside a given template and/or specialize some parts of the included template. Usually, you work by including “Node” template and specialize some parts to show a “Letter”, a “Project”, etc. Example:

<r:include template='Node'>
  <r:with part='title'/> <!-- empty (clear) title part -->
  <r:with part='content'>
    ... specialized content part
  </r:with>
</r:include>

(See name for information on how to name parts.)

You can also use it in a more traditional “partial” inclusion mechanism.

To include everything:

<r:include template='comments'/>

Or to include just some part of a template (to be avoided, see note):

<r:include template='Section' part='related'/>

Currently, such an “other template part include” actually parses the whole (here: Section) template (with all includes) before extracting the “related” part. If the “Section” template includes parts of other templates that include parts of other templates…, computation becomes very slow.

To avoid the slow template compilation of “template part includes”, copy paste the zafu you want to include into a new partial template instead. For example, into “Section/_related.zafu” and use a simple template include of the entire partial template in all places (also in orig. “Section” template). This is very fast and scales well with larger projects, where you create a sub-directory for each class that contains all its templates and partials.

Recursion

If you include a “part” without specifying a template, the part is searched in the ancestors and produces recursion:

<r:void name='grp'>
  <r:parent>
    <r:include part='grp'/> /
  </r:parent>
  <r:show attr='title'/>
</r:void>

(See name for information on how to name parts.)

The example above produces a “breadcrumb path” result (whitespace removed) like this for a “status” page:

Zena the wild CMS / projects list / Clean Water project / status title

You can augment the allowed recursion depth with depth parameter, but you won’t be allowed to go further then 30.