Inserting dynamic content
The TAL content & replace attributes behave similarly – the difference being whether the current element is preserved or not. They insert dynamic content from the TALES context into the current document.
The content and replace attributes are mutually exclusive; it is invalid to use both together.
Syntax
tal:content="MODE EXPRESSION"
tal:replace="MODE EXPRESSION"The rendering mode
The rendering mode (MODE) is optional and defaults to text if omitted. It controls how the
content of the expression is rendered into the output document. It may have one of two values:
- text indicates that the expression result is to be rendered as just that - text content. This means that the content is passed through an HTML/XML encoder (as applicable) before rendering. HTML/XML reserved characters (such as those denoting markup) will be encoded in order to render the result properly.
- structure indicates that the expression result is expected to contain markup structures, and that these should be rendered as-is without encoding.
Beware of inserting content from untrusted sources using the 'structure' rendering mode. This could lead to cross-site scripting security vulnerabilities.
The expression
The expression (EXPRESSION) is
evaluated as a TALES expression. The effect upon the document
is determined by the following logic:
| Condition | Attribute used | |
|---|---|---|
| tal:content | tal:replace | |
Expression result is null |
All child elements are removed | Element is removed from the DOM entirely |
| Expression result cancels the action | Element and its children are left unchanged | Element and its children are left unchanged |
| Expression result is any other value | All child elements are removed from the DOM and replaced with the expression result | The element and all child elements are removed from the DOM and replaced with the expression result |
Where content is inserted, if the expression result is not a System.String then it is converted
to one using the object's default ToString() method.
Elements which are removed from the DOM as a result of this operation will not have any subsequent TAL processing performed upon them.