
.. _templates:

Templates api
====================

Basic usage
------------

When using some resources, like *file_*, it  may be useful to have fully blown
template engine, than just string interpolation.

Pywizard comes with template support out of the box::

    from pywizard.api import *

    with jinja_templates(my_package_with_templates):

        file_('my_file', content=tpl('foo.txt.tpl', {'my': 'context',}))

With() construction here defines that you will use Jinja2 template engine in subsequent
tpl() calls.

You can also define your own template engine, or custom configuration of Jinja2::


    from pywizard.api import *

    templates = {'index.html': 'Hello, {{ name }}!'}

    with WithTemplateEngine(JinjaEnv(loader=DictLoader(templates))):

        file_('my_file', content=tpl('index.html', {'name': 'World',}))


tpl() function will not render your template immediately, it will return callback,
that will render template at resource execution stage. Resources like *file_* can handle this behavior.


.. automodule:: pywizard.api
   :members: jinja_templates, tpl, WithTemplateEngine
   :imported-members:

Using Template engine in your resources
-----------------------------------------

If you would like to make your custom resources to use Template engine, take a look at
function:

.. automodule:: pywizard.core.templating
   :members: compile_content
   :imported-members:

Just bypass your content through this function, if it is result of tpl() invocation,
then it will be rendered.

Custom template engine
------------------------

To implement your own totally custom template engine, You need to extend and implement
this classes:

.. automodule:: pywizard.core.templating
   :members: Template, TemplateEngine
   :imported-members:

