The base method for inserting images into a POD result is to use the document function, described in the previous section. That being said, this method has its limits, due to the fact that it implies using a POD statement. Indeed, a statement completely replaces the portion of the ODF result being its target. For example, even if you choose to anchor the image as a character, the anchored image inserted via the document function, targeted to a paragraph, will completely replace the target paragraph. Behind the scenes, POD wraps the inserted image into a new paragraph onto which the POD template's default style will be applied. Consequently, the target paragraph's general text alignment, among other characteristics, will be lost. If you need to insert an image at a precise position, within an existing paragraph whose properties must be kept (like text alignment), anchored as a character, use the image function, and not the document function. To be brief: use the image function for centering or right-aligning an image.
Use the « image » function via a POD expression, not a POD statement
Everything is in the title. The image function is one of the rare POD functions you MUST use in a POD expression, not via a POD statement.
The example below illustrates the use of this function.
It comes from a projet using the web framework part of Appy. Expression com.logo.getFilePath(com) returns the absolute path to an image file on disk. The statement conditionally injects the paragraph containing the image if this latter exists; it is a detail and it is not important for understanding the example.
What is crucial is the leading colon (:) preceding the call to the image function. If you want to undestand this, recall how a POD expression works. A POD expression is a Python expression: POD lets the Python interpreter evaluate it by calling the standard Python function eval; then, it escapes the result and injects it, replacing the field defining the expression. In our case, the image function produces a chunk of ODF code representing the image: we don't want this code to be escaped! Else, it would appear as-is, instead of being interpreted as ODF code. The colon tells Appy to avoid escaping the result of the POD expression.
When running this example, if an image is there, the result could be the following.
Don't believe I spend my time writing such ugly POD templates, surrounding images with silly sequences of childish ASCII art! My purpose was to highlight these elements:
- the image is anchored as a character; this is the only anchoring possiblity with the image function;
- the image's vertical alignment cannot (yet) be defined, and defaults to bottom alignment. I suppose that, most of the time, you will probably render the image without surrounding text.
Reference
The image function, as available in the default POD context, corresponds to method importImage defined on class Renderer. Due to the similarity with the document function, both methods share almost the same parameters, excepted those mentioned in the comments below.
def importImage(self, content=None, at=None, format=None, size=None,
sizeUnit='cm', maxWidth='page', style=None, keepRatio=True,
convertOptions=None):
'''While importDocument allows to import a document or image via a
"do ... from document" statement, method importImage allows to
import an image anchored as a char via a POD expression
":image(...)", having almost the same parameters.'''
