===============
Using Templates
===============

-------
General
-------

For config file generation, we provide a backend service which can bind
config.xml data to templates written in Jinja2
(http://jinja.pocoo.org/docs/dev/).

All available templates should be installed at the following location on
the OPNsense system:

#. /usr/local/opnsense/service/templates/


-----------------
Naming convention
-----------------

All templates should be put into a directory structure containing the
vendor and package/application name, our sample application is placed
inside the directory:

/usr/local/opnsense/service/templates/*OPNsense/Sample*

Template package content

Every template directory should contain at least 2 files:

#. a content descriptor, containing the actual targets, named +TARGETS
#. one or more template(s)


-------
Targets
-------

The +TARGETS file contains the source template name inside the template
directory and the (dynamic) target filename divided by a colon (:)
multiple lines may be inserted per file.

For example :

::

    example_simple_page.txt:/tmp/template_sample/simple_page.txt

Will create a file /tmp/template\_sample/simple\_page.txt using the
template example\_simple\_page.txt.

.. Note::

    Optionally you can specify which file or files to remove on call of "template cleanup", which can be specified by
    using an extra tag next to the target, such as:
    :code:`example_simple_page.txt:/tmp/template_sample/simple_page.txt:/tmp/template_sample/simple_page.*`

    By default all targets will be removed when calling cleanup.



If you want to use information from within the config.xml file as output
filename, you can use tags to address the content, like [version] to
input the tag version from the xml file. When generating multiple files
from 1 template, you can use one wildcard (%) to address a section of
the config file, for example [interfaces.%.if] loops over the interfaces
and outputs the value of **if**.

-----------------
Target overwrites
-----------------

Every template package can specify overwrites, which can be used by vendors who implement and maintain their own templates
for features in OPNsense.

Simply add files using the target definition in the **+TARGETS.D** directory of the templates folder using as extension **.TARGET**.

For example an overwrite for OPNsense/Sample can use the following name and location
:code:`/usr/local/opnsense/service/templates/OPNsense/Sample/+TARGETS.D/custom.TARGET`

.. Note::
    Be vey careful using this feature, you need to maintain these templates yourself and features may break after upgrades
    of OPNsense.

---------
Templates
---------

For more information of the template language itself, please look at
http://jinja.pocoo.org/docs/dev/ and the examples installed in
/usr/local/opnsense/service/templates/OPNsense/Sample.

There's one special case when using the template engine, every wildcard
used for the output file generation is also provided to the template, so
you are able to determine which filter let to this output.

Those filters are stored in the variable TARGET\_FILTERS.

.. code-block:: jinja

        {% if TARGET_FILTERS['interfaces.wan'] %}
        {% endif %}

----------
Test usage
----------

The templates can be rendered via the backend service (configd), to test
this functionality on a running OPNsense system, use:


::

    # generate template package
    configctl template reload OPNsense/Sample
    # cleanup files
    configctl template cleanup OPNsense/Sample

|

-----------------------------
Python template usage example
-----------------------------

The template system itself is a separate module which is used by
configd, to use (or test) the system without the daemon, use:

.. code-block:: python

    # import template system and config.xml handling
    from modules import template
    from modules import config
     
    # construct a new template object, set root to /tmp/
    tmpl = template.Template(target_root_directory="/tmp/")
    # open the config.xml and bind to template object
    conf = config.Config('/config.xml')
    tmpl.setConfig(conf.get())
     
    # generate output for OPNsense/Sample
    generated_filenames = tmpl.generate('OPNsense/Sample')
     
    # print results
    for filename in generated_filenames:
      print ('.. generated : %s'%filename)