The previous sections introduced you to the delicate art of writing POD templates. You have discovered and used a series of functions being available by default in any POD template. This section focuses on describing this default context, its content and behaviour.
Content
The defaut POD context is the same, be the template ODT- or ODS-based. The following table lists its precise content.
- The first column gives the name of the element, as available in the context;
- the second gives the actual Python class or method, within the appy.pod code, that is represented by this name;
- the third describes the effect of the element on the ODT or ODS result and proposes a link to the appropriate section, when relevant, giving more details about it;
- the fourth explains how / where the element must be used.
| Name in the POD context | Python class or method | Description | Usage |
|---|
| xhtml |
Method renderXhtml on class Renderer from appy/pod/renderer.py |
Injects a chunk of XHTML code, passed as a string. |
As a function call in the from clause of a POD statement |
| text |
Method renderText on class Renderer from appy/pod/renderer.py |
Injects pure text, in case the standard injection via a POD expression does not produce the desired result. |
As a function call in the from clause of a POD statement |
| document |
Method importDocument on class Renderer from appy/pod/renderer.py |
Injects another document or image (several formats are supported) into a POD result. |
As a function call in the from clause of a POD statement |
| image |
Method importImage on class Renderer from appy/pod/renderer.py |
Injects an image, anchored as a character, into a POD result via a POD expression. |
As a function call in a POD expression, prefixed with a colon (:) |
| pod |
Method importPod on class Renderer from appy/pod/renderer.py |
Injects the result of calling a sub-POD template into a main POD template. |
As a function call in the from clause of a POD statement |
| cell |
Method importCell on class Renderer from appy/pod/renderer.py |
Injects a cell with basic content and style. |
As a function call in the from clause of a POD statement |
| shape |
Method drawShape on class Renderer from appy/pod/renderer.py |
Injects a shape. Only base properties can be currently defined. |
As a function call in the from clause of a POD statement |
| TableProperties |
Class defined in appy/pod/styles_manager.py |
Class defining properties of a table. |
Create an instance of this class, within a global or local styles mapping, at key 'table' or a parameterized version of it (ie, 'table[class=myClass]') |
| BulletedProperties |
Class defined in appy/pod/styles_manager.py |
Class defining properties of a bulleted list. |
Create an instance of this class, within a global or local styles mapping, at key 'ul' or any parameterized version of it |
| NumberedProperties |
Class defined in appy/pod/styles_manager.py |
Class defining properties of a numbered list. |
Create an instance of this class, within a global or local styles mapping, at key 'ol' or any parameterized version of it |
| pageBreak |
Method insertPageBreak on class Renderer from appy/pod/renderer.py |
Injects an empty paragraph containing the ODF property "page-break-after", producing a page break. |
As a function call in the from clause of a POD statement |
| columnBreak |
Method insertColumnBreak on class Renderer from appy/pod/renderer.py |
Injects an empty paragraph containing the ODF property "column-break-after", producing a column break. To be used in sections containing more than one column. |
As a function call in the from clause of a POD statement |
| PIPE |
The string literal '|' |
The pipe char (|) cannot be used within POD expressions or statements, even within a string literal. Use context variable PIPE instead. |
As a variable in a POD statement or expression. |
| SEMICOLON |
The string literal ';' |
The semicolon char (;) cannot be used within POD expressions or statements in string literals. Use context variable SEMICOLON instead. |
As a variable in a POD statement or expression. |
| loop |
A instance of class Object from appy/model/utils.py |
This object stores information about the currently walked for loops produced by the corresponding for statements. You can find more information about this in the section dedicated to the for statement.
WARNING. If you pass a variable named "loop" in the context, the POD's behaviour will be undefined. Unlike the other names, POD cannot overwrite this key in the context, because of context transmission between a renderer and sub-renderers.
|
Access it as an instance object in POD statements or expressions being inside a for statement. |
Behaviour
When you pass a context to the Renderer, in parameter context, POD will update it with the entries as specified in the previous table. In the context parameter, you can pass:
- a Python dict;
- a Python object (in that case, this objet's __dict__ parameter will be used);
- an instance of class UserDict.
In any of these cases, POD will take the freedom of modifying the passed dict or object. Consequently:
- be careful if you plan to reuse your context elsewhere: POD modifies it in any case;
- if your context defines any of the POD-reserved names, they will be overridden by POD's own methods, functions or variables.
While an ODT result is being processed, the context evolves: entries are added and removed, while encountering for and with statements. Such statements add variables in the context: the iterator variable(s) for for statements, and variable definitions for with statements. But these variables are only applicable in the scope defined by the statement, which is the element, in the ODT document (paragraph, table, section...) being the target of the statement. For example, suppose the following for statement applies to the first paragraph of an ODT document containing 2 paragraphs:
do text for elem in someList
Variable elem will be added to the context, but only while rendering (and, in that case, repeating) the paragraph being the target of this statement (the first one). Trying to use variable elem in the second paragrah leads to undefined behaviour.
Hidden variables
In the previous example, what could happen if, for example, name elem was already defined in the context before encountering the for statement ? While managing the for statement, the global variable referred as name elem will be hidden: it will not be available in this part of the document, because elem, at this point, will be reused to denote, successively, every element from list "someList". That being said, after having executed the for statement, the global variable named elem will be reified and will again be available in the remaining parts of the POD template.
Statements can be defined on ODT elements being contained within other ODT elements. For example, a statement may be defined on a section containing a table, onto which another statement is defined; we can continue and define other statements on table parts: rows, cells and cell's inner paragraphs. Every statement defines a kind of scope, potentially hiding any variable from the outer scope, itself potentially hiding variables from its own outer scope, etc. POD manages these scopes with variable hiding and reification, at any level within an POD template.
