TALES 'load' expressions

The TALES load expression is used to render another document (or a METAL macro within a document) and return the result of that rendering.

Load expressions allow TAL to perform element-replacement akin to METAL, although in a very limited manner.

Syntax

load:EXPRESSION

The content of a load: expression is treated itself as an expression (the 'inner expression'). Any valid expression is acceptable, although it should generally evaluate to either a ZPT document or a ZPT macro.

Behaviour

The logic for the evaluation of a load expression is as follows:

• If the inner expression evaluates to a ZPT document then that entire document will be rendered using ZPT.
• If the inner expression evaluates to a ZPT macro then that macro will be copied to a new (empty) ZPT document and rendered.
• If the inner expression cancels the action then the load expression will also cancel the action.
• If the inner expression evaluates to null then the load expression will evaluate to null.
• If an inner expression evaluates to anything which is not one one of the above then an error will be raised.

In both of the cases where a document is loaded and rendered, the result of that rendering (as a string) will be returned as the value of the load expression.

Rendering loaded content

Load expressions, even though they may reference METAL macros, are not METAL. Thus, a load expression may not directly fill slots, or extend a macro. When documents are rendered using a load expression, they are rendered as a 'standlone' document. The one exception to this is that the loaded document has access to all of the variables defined within the parent.

When a document or macro is loaded, the load expression evaluator defines new local TALES variables for every variable that is currently in-scope where the load attribute appeared. Thus, documents loaded via an expression may make some use of the calling document's model.

Use case for load expressions

The preferred mechanism for re-using markup from other source files is METAL. Macros, slots and macro extension should suffice in most cases.

One instance where METAL is of no use is where the content to be re-used is not known at design-time. METAL is evaluated and fully resolved before TAL processing begins.

A non-functioning example

Consider the following example; at face value it looks like it would dynamically select a METAL macro, based upon the product used for the repetition statement. However, this will not work. The use-macro attribute will be evaluated and resolved before any of the TAL attributes.

<ul>
  <li tal:repeat="product here/ProductList">
    <div tal:define="macroName product/GetMacroName;
                     macro here/Documents/ProductTemplates/macros/?macroName"
         metal:use-macro="macro"
         class="product_summary">
      Product summary content controlled by a dynamically-selected macro.
    </div>
  </li>
</ul>

Using a load expression

Let us revisit the intention of the example above - to insert content which is dynamically-selected based upon TAL variables. Here is where the load expression becomes useful.

<ul>
  <li tal:repeat="product here/ProductList">
    <div tal:define="macroName product/GetMacroName;
                     macro here/Documents/ProductTemplates/macros/?macroName;
                     macroContent load:macro"
         class="product_summary"
         tal:replace="structure macroContent">
      Product summary content controlled by a dynamically-selected macro.
    </div>
  </li>
</ul>

The document containing the reusable content is rendered and loaded into the variable macroContent. This is then paired with a tal:replace attribute, using the structure keyword.