Grantlee: Internals

Grantlee 5.3.0

Internals

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

# How Grantlee 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.