`gws.plugin.template.html`¶

HTML templates.

The html template is written in the Jump template language. It produces HTML and, for printing, PDF or PNG output. PDF and PNG are rendered from the generated HTML (gws.lib.htmlx). The output type is the mimeOut of the render input, or the first configured mimeTypes entry, or HTML. The template source is given as text or as a file path; a template file is recompiled when it changes.

The arguments passed to a template can be accessed via the _ARGS object.

If a template explicitly returns a gws.Response object, the generated text is ignored and the object is returned as the render result. Otherwise, the result is a gws.ContentResponse object with the generated content.

This template supports the following extensions to Jump.

The @page command, which sets parameters for the printed page:

@page (
    width="<page width in mm>"
    height="<page height in mm>"
    margin="<page margins in mm, one value or four values>"
)

The @map command, which renders a map of the render input:

@map (
    width="<width in mm>"
    height="<height in mm>"
    number="<optional, index of the map, 0 by default>"
    bbox="<optional, bounding box in projection units>"
    center="<optional, center coordinates in projection units>"
    scale="<optional, scale>"
    rotation="<optional, rotation in degrees>"
)

The @legend command, which renders the legend of the visible layers of a map, or of the given layers:

@legend (
    number="<optional, index of the map, 0 by default>"
    layers="<optional, space separated list of layer UIDs>"
)

The @header and @footer block commands, which define headers and footers for multi-page printing:

@header
    content
@end header

@footer
    content
@end footer

Headers and footers are separate sub-templates, which receive the same arguments as the main template and two additional arguments:

numpages - the total number of pages in the document
page - the current page number

They are rendered as a separate PDF, which is placed over the content PDF.

The @pagebreak command, which renders a page break.

Example:

templates+ {
    subject "feature.title"
    type "html"
    text "{{name}}"
}

printers+ {
    template {
        type "html"
        path "/data/templates/print.cx.html"
        mimeTypes [ "application/pdf" ]
    }
}

Source code: gws.plugin.template.html

Package Contents¶

class gws.plugin.template.html.Config¶

Bases: gws.base.template.Config

Jump template that renders HTML, PDF or image output.

path: gws.FilePath | None¶: Template file.

text: str = ''¶: Template source.

class gws.plugin.template.html.Engine(template: Object, tri: gws.TemplateRenderInput | None = None)¶

Bases: gws.lib.vendor.jump.Engine

Jump engine with the commands of HTML templates.

The engine collects the page settings, header and footer defined by the template while it renders.

footer: str = ''¶: Footer source set by @footer.

header: str = ''¶: Header source set by @header.

pageMargin: list[int] = []¶: Page margins set by @page.

pageSize: gws.UomSize = []¶: Page size set by @page.

template¶

tri = None¶

def_legend(**kw)¶

Handle the @legend command.

Parameters:: **kw – Command arguments number and layers.
Returns:: HTML fragment.

def_map(**kw)¶

Handle the @map command.

Parameters:: **kw – Command arguments width, height, number, bbox, center, scale and rotation.
Returns:: HTML fragment.

def_page(**kw)¶

Handle the @page command.

Parameters:: **kw – Command arguments width, height and margin.

def_pagebreak(**kw)¶

Handle the @pagebreak command.

Parameters:: **kw – Command arguments, not used.
Returns:: HTML fragment.

mbox_footer(text)¶

Handle the @footer block command.

Parameters:: text – Footer template source.

mbox_header(text)¶

Handle the @header block command.

Parameters:: text – Header template source.

class gws.plugin.template.html.Object¶

Bases: gws.base.template.Object

Jump template that renders HTML, PDF or PNG output.

compiledFn = None¶: Compiled template function.

compiledTime: float = 0¶: Time of the last compilation.

path: str¶: Template file path.

text: str¶: Template source.

compile(engine: Engine)¶

Compile the template if needed.

The template file is read again if it has changed since the last compilation. With the developer option template.always_reload, the template is compiled on each call; with template.save_compiled, the translated source is written to a debug file.

Parameters:: engine – Jump engine.

configure()¶

decorate_html(html)¶

Add the charset and, for file templates, a base URL to the HTML.

The base URL is the template directory, so that relative paths in the template are resolved against it.

Parameters:: html – HTML text.
Returns:: Decorated HTML.

error_handler(exc, path, line, env)¶

Handle a template runtime error.

The error is logged. With the developer option template.raise_errors, the error is raised, otherwise rendering continues.

Parameters:

exc – The exception.
path – Template path.
line – Template line.
env – Template environment.

Returns:

True to continue rendering, False to raise the error.

finalize(tri: gws.TemplateRenderInput, html: str, args: gws.TemplateArgs, main_engine: Engine)¶

Convert the generated HTML into the output format.

Parameters:

tri – Template render input.
html – Generated HTML.
args – Template arguments.
main_engine – Engine that rendered the HTML, holds the page settings, header and footer.

Returns:

Content response with HTML, or a PDF or PNG file.

Raises:

gws.Error – If the output MIME type is not supported.

finalize_pdf(tri: gws.TemplateRenderInput, html: str, args: gws.TemplateArgs, main_engine: Engine)¶

Render the generated HTML as PDF.

If a header or footer is defined, they are rendered on a separate PDF, one page per content page, which is placed over the content.

Parameters:

tri – Template render input.
html – Generated HTML.
args – Template arguments.
main_engine – Engine that rendered the HTML.

Returns:

Path to the PDF file.

finalize_png(tri: gws.TemplateRenderInput, html: str, args: gws.TemplateArgs, main_engine: Engine)¶

Render the generated HTML as PNG.

Parameters:

tri – Template render input.
html – Generated HTML.
args – Template arguments.
main_engine – Engine that rendered the HTML.

Returns:

Path to the PNG file.

frame_template(header, footer, page_size)¶

Create the Jump source of the header and footer frame.

The frame has one page per content page, with the header at the top and the footer at the bottom.

Parameters:

header – Header template source.
footer – Footer template source.
page_size – Page size in mm.

Returns:

Template source.

render(tri)¶

render_legend(tri: gws.TemplateRenderInput, index, layers)¶

Render a legend as an HTML image tag.

Parameters:

tri – Template render input.
index – Index of the map in tri.maps, whose visible layers are used by default.
layers – Layer UIDs to use instead of the visible layers.

Returns:

An img tag pointing to the legend image, or None if there is no legend.

render_map(tri: gws.TemplateRenderInput, width, height, index, bbox=None, center=None, scale=None, rotation=None)¶

Render a map of the render input as HTML.

Parameters:

tri – Template render input.
width – Map width in mm.
height – Map height in mm.
index – Index of the map in tri.maps.
bbox – Bounding box, defaults to the bounding box of the map.
center – Center, defaults to the center of the map.
scale – Scale, defaults to the scale of the map.
rotation – Rotation in degrees, defaults to the rotation of the map.

Returns:

HTML fragment.

render_page_break(tri: gws.TemplateRenderInput)¶

Render a page break.

Parameters:: tri – Template render input.
Returns:: HTML fragment.

class gws.plugin.template.html.Props¶: Bases: gws.base.template.Props

`gws.plugin.template.html`¶

Package Contents¶

Table of Contents

Previous topic

Next topic

gws.plugin.template.html¶

Package Contents¶

`gws.plugin.template.html`¶