Internals

Note

This page is intended only to be informative for new contributors to KTextTemplate or people who are really interested in this kind of thing. These are implementation details and are likely to change without notice.

How KTextTemplate works.

A template string is first tokenized by the Lexer class. The result is a list of tokens with content which can be of type TextToken, CommentToken, VariableToken or TagToken.

The tokens are further processed by the Parser class. The Parser generates nodes from the token stream. For a TextToken it generates a TextNode, for a CommentToken it generates nothing, for a VariableToken it generates a VariableNode, and for a TagToken it generates another type of Node determined by available plugins. Some plugins are built in, and others may be loaded by the template itself using the {% load %} tag, or preloaded by the application developer.

The plugin uses the Abstract Factory Pattern. It returns a list of concrete factories, one for each tag handled by that plugin. The factories have a getNode method which accepts the tag content and the active parser as an argument and returns a concrete Node. The getNode method may advance the parser in the case of begin/end tags etc. When the parser is finished, it has created a tree of nodes, which is essentially a Template object.

A Template is rendered with a Context object. During rendering, each node in the template has its render method called with the Context. The Node may contain different sub-trees, one of which is rendered, as is the case for IfNode, or it might contain a single sub-tree which is rendered multiple times, as in the case of ForNode, etc. The rendering outputs a string, which is the rendered output of the Template for a particular Context. A single Template may be rendered multiple times with mutliple different Contexts.

Plugins can return Filter and AbstractNodeFactory instances. Filters can manipulate Variable instances in some way before rendering them to the output.

Loading templates to include or extend is accomplished using the loadByName methods. The secondary template should use the same state as the initially created/loaded template, so that it uses the same template loaders, has the same plugins available by default and uses the same search directories to find additional plugins.