python-jingo 0.7-2 / usr / lib / python2.7 / dist-packages / jingo-0.7.egg-info / PKG-INFO

Metadata-Version: 1.1
Name: jingo
Version: 0.7
Summary: An adapter for using Jinja2 templates with Django.
Home-page: http://github.com/jbalogh/jingo
Author: Jeff Balogh
Author-email: jbalogh@mozilla.com
License: BSD
Description: .. _jingo:
        .. module:: jingo
        
        =====
        Jingo
        =====
        
        .. note:: This document may be out of date.  The up-to-date documentation can
           be found on `Read the Docs <https://jingo.readthedocs.org/en/latest/>`_.
        
        
        Jingo is an adapter for using Jinja2_ templates within Django.
        
        .. note:: Coffin or Jingo?
        
            Jingo differs from Coffin_ in two major ways:
        
            * Jingo serves purely as a minimalistic bridge between Django and Jinja2_.
              Coffin_ attempts to reduce the differences between Jinja2_ templates
              and Django's native templates.
        
            * Jingo has a far superior name, as it is a portmanteau of 'Jinja' and
              Django.
        
            .. _Coffin: https://github.com/coffin/coffin/
            .. _Jinja2: http://jinja.pocoo.org/2/
        
        
        .. _usage:
        
        Usage
        -----
        
        When configured properly (see Settings_ below) you can render Jinja2_ templates in
        your view the same way you'd render Django templates::
        
            from django.shortcuts import render
        
        
            def my_view(request):
                context = dict(user_ids=(1, 2, 3, 4))
                return render(request, 'users/search.html', context)
        
        .. note::
        
            Not only does ``django.shorcuts.render`` work, but so does any method that
            Django provides to render templates.
        
        .. _settings:
        
        Settings
        --------
        
        You'll want to use Django to use jingo's template loader.
        In ``settings.py``::
        
            TEMPLATE_LOADERS = (
                'jingo.Loader',
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            )
        
        This will let you use ``django.shortcuts.render`` or
        ``django.shortcuts.render_to_response``.
        
        You can optionally specify which filename patterns to consider Jinja2 templates::
        
            JINGO_INCLUDE_PATTERN = r'\.jinja2'  # use any regular expression here
        
        This will consider every template file that contains the substring `.jinja2` to
        be a Jinja2 file (unless it's in a module explicitly excluded, see below).
        
        And finally you may have apps that do not use Jinja2, these must be excluded
        from the loader::
        
            JINGO_EXCLUDE_APPS = ('debug_toolbar',)
        
        If a template path begins with ``debug_toolbar``, the Jinja loader will raise a
        ``TemplateDoesNotExist`` exception. This causes Django to move onto the next
        loader in ``TEMPLATE_LOADERS`` to find a template - in this case,
        ``django.template.loaders.filesystem.Loader``.
        
        .. note::
           Technically, we're looking at the template path, not the app. Often these are
           the same, but in some cases, like 'registration' in the default setting--which
           is an admin template--they are not.
        
        The default is in ``jingo.EXCLUDE_APPS``::
        
            EXCLUDE_APPS = (
                'admin',
                'admindocs',
                'registration',
                'context_processors',
            )
        
        .. versionchanged:: 0.6.2
           Added ``context_processors`` application.
        
        If you want to configure the Jinja environment, use ``JINJA_CONFIG`` in
        ``settings.py``.  It can be a dict or a function that returns a dict. ::
        
            JINJA_CONFIG = {'autoescape': False}
        
        or ::
        
            def JINJA_CONFIG():
                return {'the_answer': 41 + 1}
        
        
        Template Helpers
        ----------------
        
        Instead of template tags, Jinja encourages you to add functions and filters to
        the templating environment.  In ``jingo``, we call these helpers.  When the
        Jinja environment is initialized, ``jingo`` will try to open a ``helpers.py``
        file from every app in ``INSTALLED_APPS``.  Two decorators are provided to ease
        the environment extension:
        
        .. function:: jingo.register.filter
        
            Adds the decorated function to Jinja's filter library.
        
        .. function:: jingo.register.function
        
            Adds the decorated function to Jinja's global namespace.
        
        
        .. highlight:: jinja
        
        Default Helpers
        ~~~~~~~~~~~~~~~
        
        Helpers are available in all templates automatically, without any extra
        loading.
        
        .. automodule:: jingo.helpers
            :members:
        
        
        Template Environment
        --------------------
        
        A single Jinja ``Environment`` is created for use in all templates.  This is
        available as ``jingo.env`` if you need to work with the ``Environment``.
        
        
        Localization
        ------------
        
        Since we all love L10n, let's see what it looks like in Jinja templates::
        
            <h2>{{ _('Reviews for {0}')|f(addon.name) }}</h2>
        
        The simple way is to use the familiar underscore and string within a ``{{ }}``
        moustache block.  ``f`` is an interpolation filter documented below.  Sphinx
        could create a link if I knew how to do that.
        
        The other method uses Jinja's ``trans`` tag::
        
            {% trans user=review.user|user_link, date=review.created|datetime %}
                by {{ user }} on {{ date }}
            {% endtrans %}
        
        ``trans`` is nice when you have a lot of text or want to inject some variables
        directly.  Both methods are useful, pick the one that makes you happy.
        
        
        Forms
        -----
        
        Django marks its form HTML "safe" according to its own rules, which Jinja2 does
        not recognize.
        
        This monkeypatches Django to support the ``__html__`` protocol used in Jinja2
        templates. ``Form``, ``BoundField``, ``ErrorList``, and other form objects that
        render HTML through their ``__unicode__`` method are extended with ``__html__``
        so they can be rendered in Jinja2 templates without adding ``|safe``.
        
        Call the ``patch()`` function to execute the patch. It must be called
        before ``django.forms`` is imported for the conditional_escape patch to work
        properly. The root URLconf is the recommended location for calling ``patch()``.
        
        Usage::
        
            import jingo.monkey
            jingo.monkey.patch()
        
        
        Testing
        -------
        
        To run the test suite, you need to define ``DJANGO_SETTINGS_MODULE`` first::
        
            $ export DJANGO_SETTINGS_MODULE="fake_settings"
            $ nosetests
        
        or simply run::
        
            $ python run_tests.py
        
        To test on all supported versions of Python and Django::
        
            $ pip install tox
            $ tox
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Environment :: Web Environment :: Mozilla
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Software Development :: Libraries :: Python Modules