======================
 Appy Engine
======================

This package provides a Template engine suitable to render templates created
with OpenDocument format ``.odt``, ``.ods``, i.e. the native format for
OpenOffcie/LibreOffice. It uses package ``appy.pod`` module from the appy_
package that uses variable placeholder and code written in LibreOffice's
comment.

a Template engine is declared in your settings alongside DjangoTemplate::

  TEMPLATES = [
      {
        ## First position is IMPORTANT!!!
        'BACKEND': 'thx.appy.AppyPodEngine',
        'DIRS': [],
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.request',
                'apps.examples.context_processors.thux'  # just an example
            ],
            'loaders': [
                'thx.appy.loader.FilesystemLoader',
                'thx.appy.loader.AppDirectoriesLoader',
            ]
        },
      },
      {
          'BACKEND': 'django.template.backends.django.DjangoTemplates',
          'DIRS': [],
          'APP_DIRS': True,
          'OPTIONS': {
              # ... some options here ...
          },
      },
      {
  ]


This allows you to use it in a very simple way, eg in ``urls.py``::

  path('pdf', AppyTemplateView.as_view(template_name="examples/simple.odt")

Or using django template's API as in::

  from django.template import loader
  tpl = loader.get_template('example/SampleWithContext.odt', using='appy')
  pdf = tpl.render({'name': 'Thux'})
  with open(dest, 'wb') as f:
      f.write(pdf)

or using special method ``save_as``::

  from django.template import loader
  tpl = loader.get_template('example/SampleWithContext.odt')
  tpl.save_as(context=my_context)


Settings
=========

You need to create the section in TEMPLATES variable as shown above. It's
important you set it in first position as otherwise DjangoTemplate tries to find
the file and will fail trying to interpret binary with an encoding.

``AppyPodTemplate`` loader will exit immediately on file type other than
``.odt`` and ``.ods``.

There are some settings that influence the behaviour:

:POD_CONVERTER: the external service able to do the format conversion. Deve
                essere una server gotenberg_

:UNO_PYTHON_PATH: the local Python path that has ``uno`` module to make the
                  format conversion (faster)

:UNO_OOO_PORT: the local port where soffice is listening (defaul 8100) needed
               only if local conversion is required.


.. _appy: http://appyframework.org/pod.html
.. _gotenberg: https://thecodingmachine.github.io/gotenberg/