:tocdepth: 3

:py:mod:`gws.plugin.template.html`
==================================

.. py:module:: gws.plugin.template.html

.. autoapi-nested-parse::

   HTML template.

   This module handles templates written in the Jump language. Apart from html, this template can generate pdf (for printing) and image outputs.

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

   If a template explicitly returns a :obj:`gws.Response` object, the generated text is ignored and the object is returned as a render result.
   Otherwise, the result of the rendering will be a :obj:`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>"
       )

   The ``@map`` command, which renders the current map::

       @map (
           width="<width in mm>"
           height="<height in mm>"
           bbox="<optional, bounding box in projection units>"
           center="<optional, center coordinates in projection units>"
           scale="<optional, scale factor>"
           rotation="<optional, rotation in degrees>"


   The ``@legend`` command, which renders the map legend::

       @legend(
           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

   The ``@pagebreak`` command, which renders a page break.



**Source code:** :source:`gws.plugin.template.html<gws/plugin/template/html/__init__.py>`



Package Contents
----------------



.. py:class:: Config


   Bases: :py:obj:`gws.base.template.Config`

   HTML template configuration.

   .. py:attribute:: path
      :type:  Optional[gws.FilePath]

      Path to a template file.

   .. py:attribute:: text
      :type:  str
      :value: ''


      Template content.


.. py:class:: Engine(template: Object, tri: Optional[gws.TemplateRenderInput] = None)


   Bases: :py:obj:`gws.lib.vendor.jump.Engine`

   .. py:attribute:: footer
      :type:  str
      :value: ''


   .. py:attribute:: header
      :type:  str
      :value: ''


   .. py:attribute:: pageMargin
      :type:  list[int]
      :value: []


   .. py:attribute:: pageSize
      :type:  gws.UomSize
      :value: []


   .. py:attribute:: template

   .. py:attribute:: tri
      :value: None


   .. py:method:: def_legend(**kw)

   .. py:method:: def_map(**kw)

   .. py:method:: def_page(**kw)

   .. py:method:: def_pagebreak(**kw)

   .. py:method:: mbox_footer(text)

   .. py:method:: mbox_header(text)


.. py:class:: Object


   Bases: :py:obj:`gws.base.template.Object`

   .. py:attribute:: compiledFn
      :value: None


   .. py:attribute:: compiledTime
      :type:  float
      :value: 0


   .. py:attribute:: path
      :type:  str

   .. py:attribute:: text
      :type:  str

   .. py:method:: compile(engine: Engine)

   .. py:method:: configure()

   .. py:method:: decorate_html(html)

   .. py:method:: error_handler(exc, path, line, env)

   .. py:method:: finalize(tri: gws.TemplateRenderInput, html: str, args: dict, main_engine: Engine)

   .. py:method:: finalize_pdf(tri: gws.TemplateRenderInput, html: str, args: dict, main_engine: Engine)

   .. py:method:: finalize_png(tri: gws.TemplateRenderInput, html: str, args: dict, main_engine: Engine)

   .. py:method:: frame_template(header, footer, page_size)

   .. py:method:: render(tri)

   .. py:method:: render_legend(tri: gws.TemplateRenderInput, index, layers)

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

   .. py:method:: render_page_break(tri: gws.TemplateRenderInput)


.. py:class:: Props


   Bases: :py:obj:`gws.base.template.Props`