core.render.html
================

.. py:module:: core.render.html


Submodules
----------

.. toctree::
   :maxdepth: 1

   /viur/core/render/html/default/index
   /viur/core/render/html/env/index
   /viur/core/render/html/utils/index


Classes
-------

.. autoapisummary::

   core.render.html.default


Functions
---------

.. autoapisummary::

   core.render.html.jinjaGlobalExtension
   core.render.html.jinjaGlobalFilter
   core.render.html.jinjaGlobalFunction
   core.render.html.jinjaGlobalTest


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

.. py:class:: default(*args, **kwargs)

   Bases: :py:obj:`core.render.abstract.AbstractRenderer`


   The core jinja2 render.

   This is the bridge between your ViUR modules and your templates.
   First, the default jinja2-api is exposed to your templates. See http://jinja.pocoo.org/ for
   more information. Second, we'll pass data das global variables to templates depending on the
   current action.

       - For list() a `skellist` is provided containing all requested skeletons to a limit
       - For view(): skel - a dictionary with values from the skeleton prepared for use inside html
       - For add()/edit: a dictionary as `skel` with `values`, `structure` and `errors` as keys.

   Third, a bunch of global filters (like urlencode) and functions (getEntry, ..) are available  to templates.

   See the ViUR Documentation for more information about functions and data available to jinja2 templates.

   Its possible for modules to extend the list of filters/functions available to templates by defining
   a function called `jinjaEnv`. Its called from the render when the environment is first created and
   can extend/override the functionality exposed to templates.



   .. py:attribute:: kind
      :value: 'html'


      Renderer type specifier



   .. py:attribute:: listTemplate
      :value: 'list'



   .. py:attribute:: viewTemplate
      :value: 'view'



   .. py:attribute:: addTemplate
      :value: 'add'



   .. py:attribute:: editTemplate
      :value: 'edit'



   .. py:attribute:: addSuccessTemplate
      :value: 'add_success'



   .. py:attribute:: editSuccessTemplate
      :value: 'edit_success'



   .. py:attribute:: deleteSuccessTemplate
      :value: 'delete_success'



   .. py:attribute:: listRepositoriesTemplate
      :value: 'list_repositories'



   .. py:attribute:: __haveEnvImported_
      :value: False



   .. py:method:: getTemplateFileName(template, ignoreStyle = False, raise_exception = True)

      Returns the filename of the template.

      This function decides in which language and which style a given template is rendered.
      The style is provided as get-parameters for special-case templates that differ from
      their usual way.

      It is advised to override this function in case that
      :func:`viur.core.render.jinja2.default.Render.getLoaders` is redefined.

      :param template: The basename of the template to use. This can optionally be also a sequence of names.
      :param ignoreStyle: Ignore any maybe given style hints.
      :param raise_exception: Defaults to raise an exception when not found, otherwise returns None.

      :returns: Filename of the template



   .. py:method:: getLoaders()

      Return the list of Jinja2 loaders which should be used.

      May be overridden to provide an alternative loader
      (e.g. for fetching templates from the datastore).



   .. py:method:: renderBoneValue(bone, skel, key, boneValue, isLanguageWrapped = False)

      Renders the value of a bone.

      It can be overridden and super-called from a custom renderer.

      :param bone: The bone which value should be rendered.
          (inherited from :class:`viur.core.bones.base.BaseBone`).
      :param skel: The skeleton containing the bone instance.
      :param key: The name of the bone.
      :param boneValue: The value of the bone.
      :param isLanguageWrapped: Is this bone wrapped inside a :class:`LanguageWrapper`?

      :return: A dict containing the rendered attributes.



   .. py:method:: get_template(action, template)

      Internal function for retrieving a template from an action name.



   .. py:method:: render_action_template(default, skel, action, tpl = None, params = None, **kwargs)

      Internal action rendering that provides a variable structure to render an input-form.
      The required information is passed via skel["structure"], skel["value"] and skel["errors"].

      Any data in **kwargs is passed unmodified to the template.

      :param default: The default action to render, which is used to construct a template name.
      :param skel: Skeleton of which should be used for the action.
      :param action: The name of the action, which is passed into the template.
      :param tpl: Name of a different template, which should be used instead of the default one.
      :param params: Optional data that will be passed unmodified to the template.

      Any data in **kwargs is passed unmodified to the template.

      :return: Returns the emitted HTML response.



   .. py:method:: render_view_template(default, skel, action, tpl = None, params = None, **kwargs)

      Renders a page with an entry.

      :param default: The default action to render, which is used to construct a template name.
      :param skel: Skeleton which contains the data of the corresponding entity.
      :param action: The name of the action, which is passed into the template.
      :param tpl: Name of a different template, which should be used instead of the default one.
      :param params: Optional data that will be passed unmodified to the template

      Any data in **kwargs is passed unmodified to the template.

      :return: Returns the emitted HTML response.



   .. py:method:: list(skellist, action = 'list', tpl = None, params = None, **kwargs)

      Renders a page with a list of entries.

      :param skellist: List of Skeletons with entries to display.
      :param action: The name of the action, which is passed into the template.
      :param tpl: Name of a different template, which should be used instead of the default one.

      :param params: Optional data that will be passed unmodified to the template

      Any data in **kwargs is passed unmodified to the template.

      :return: Returns the emitted HTML response.



   .. py:method:: view(skel, action = 'view', tpl = None, params = None, **kwargs)

      Renders a page for viewing an entry.

      For details, see self.render_view_template().



   .. py:method:: add(skel, action = 'add', tpl = None, params = None, **kwargs)

      Renders a page for adding an entry.

      For details, see self.render_action_template().



   .. py:method:: edit(skel, action = 'edit', tpl = None, params = None, **kwargs)

      Renders a page for modifying an entry.

      For details, see self.render_action_template().



   .. py:method:: addSuccess(skel, action = 'addSuccess', tpl = None, params = None, **kwargs)

      Renders a page, informing that an entry has been successfully created.

      For details, see self.render_view_template().



   .. py:method:: editSuccess(skel, action = 'editSuccess', tpl = None, params = None, **kwargs)

      Renders a page, informing that an entry has been successfully modified.

      For details, see self.render_view_template().



   .. py:method:: deleteSuccess(skel, action = 'deleteSuccess', tpl = None, params = None, **kwargs)

      Renders a page, informing that an entry has been successfully deleted.

      For details, see self.render_view_template().



   .. py:method:: listRootNodes(repos, action = 'listrootnodes', tpl = None, params = None, **kwargs)

      Renders a list of available root nodes.

      :param repos: List of repositories (dict with "key"=>Repo-Key and "name"=>Repo-Name)
      :param action: The name of the action, which is passed into the template.
      :param tpl: Name of a different template, which should be used instead of the default one.
      :param params: Optional data that will be passed unmodified to the template

      Any data in **kwargs is passed unmodified to the template.

      :return: Returns the emitted HTML response.



   .. py:method:: render(action, skel = None, *, tpl = None, next_url = None, **kwargs)

      Universal rendering function.

      Handles an action and a skeleton. It shall be used by any action, in future.
      It additionally allows for a tpl-parameter in HTML-renderer.



   .. py:method:: renderEmail(dests, file = None, template = None, skel = None, **kwargs)

      Renders an email.
      Uses the first not-empty line as subject and the remaining template as body.

      :param dests: Destination recipients.
      :param file: The name of a template from the deploy/emails directory.
      :param template: This string is interpreted as the template contents. Alternative to load from template file.
      :param skel: Skeleton or dict which data to supply to the template.
      :return: Returns the rendered email subject and body.



   .. py:method:: getEnv()

      Constructs the Jinja2 environment.

      If an application specifies an jinja2Env function, this function
      can alter the environment before its used to parse any template.

      :return: Extended Jinja2 environment.



.. py:function:: jinjaGlobalExtension(ext)

   Function for activating extensions in Jinja2.


.. py:function:: jinjaGlobalFilter(f)

   Decorator, marks a function as a Jinja2 filter.


.. py:function:: jinjaGlobalFunction(f)

   Decorator, marks a function as a Jinja2 global.


.. py:function:: jinjaGlobalTest(func_or_alias)

   Decorator, marks a function as a Jinja2 test.

   To avoid name conflicts you can call the decorator
   with an alias as first argument.
   Otherwise, the test will be registered under the function name.

       ..  code-block:: python

           # Example:
           from viur.core.render.html import jinjaGlobalTest
           # @jinjaGlobalTest  # available under "positive_number"

           @jinjaGlobalTest("positive")  # available under "positive"
           def positive_number(render, value):
               return isinstance(value, int) and value > 0