Permalink
Browse files

Updated jinja docs.

  • Loading branch information...
1 parent f1b0367 commit 1dc0e0bf4a0118ef53adc6967537a511152a040a @davedash davedash committed Oct 26, 2011
Showing with 211 additions and 24 deletions.
  1. +146 −3 README.rst
  2. +5 −0 docs/Makefile
  3. +5 −0 docs/README.stub
  4. +2 −1 docs/conf.py
  5. +53 −20 docs/index.rst
View
149 README.rst
@@ -1,10 +1,153 @@
+.. _jingo:
+.. module:: jingo
=====
Jingo
=====
-``jingo`` is an adapter for using
-`Jinja2 <http://jinja.pocoo.org/2/documentation/>`_ templates within Django.
+Jingo is an adapter for using Jinja2_ templates within Django.
+.. note:: Coffin or Jingo?
-See the full docs at http://jbalogh.me/projects/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 supperior 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 MyView(request):
+ # TODO: Do something.
+ context = dict(user_ids=[1, 2, 3, 4])
+ render('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``.
+
+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 is in the *app folder*, ``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``.
+
+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.
+
+
+Testing
+-------
+
+Testing is handle via fabric::
+
+ fab test
+
+
+.. seealso:
+ The full documentation is available at http://jinja.rtfd.org/ or in the
+ docs/ folder.
View
5 docs/Makefile
@@ -16,6 +16,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
help:
@echo "Please use \`make <target>' where <target> is one of"
+ @echo " readme to copy index.rst to ../README.rst"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " pickle to make pickle files"
@@ -30,6 +31,10 @@ help:
clean:
-rm -rf $(BUILDDIR)/*
+readme:
+ cat index.rst > ../README.rst
+ cat README.stub >> ../README.rst
+
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
View
5 docs/README.stub
@@ -0,0 +1,5 @@
+
+
+.. seealso:
+ The full documentation is available at http://jinja.rtfd.org/ or in the
+ docs/ folder.
View
3 docs/conf.py
@@ -2,6 +2,7 @@
import sys
sys.path.append(os.path.abspath('..'))
+os.environ['DJANGO_SETTINGS_MODULE'] = 'fake_settings'
import jingo
@@ -15,7 +16,7 @@
# General information about the project.
project = u'Jingo'
-copyright = u'2010, The Zamboni Collective'
+copyright = u'2010-2011, The Mozilla Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
View
73 docs/index.rst
@@ -5,29 +5,51 @@
Jingo
=====
-Jingo is an adapter for using
-`Jinja2 <http://jinja.pocoo.org/2/documentation/>`_ templates within Django.
-Why are we already replacing the templates? AMO's current PHP templates let you
-go hog-wild with logic in the templates, while Django is extremely restrictive.
-Jinja loosens those restrictions somewhat, providing a more powerful engine with
-the beauty of Django's templates. The tipping point for me was the verbosity of
-doing L10n in Django templates.
+Jingo is an adapter for using Jinja2_ templates within Django.
+.. note:: Coffin or Jingo?
-Settings
---------
+ Jingo differs from Coffin_ in two major ways:
-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. ::
+ * 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.
- JINJA_CONFIG = {'autoescape': False}
+ * Jingo has a far supperior name, as it is a portmanteau of 'Jinja' and
+ Django.
-or ::
+ .. _Coffin: https://github.com/coffin/coffin/
+ .. _Jinja2: http://jinja.pocoo.org/2/
- def JINJA_CONFIG():
- return {'the_answer': 41 + 1}
-You'll want to use jingo's template loader::
+.. _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 MyView(request):
+ # TODO: Do something.
+ context = dict(user_ids=[1, 2, 3, 4])
+ render('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',
@@ -43,10 +65,21 @@ from the loader::
JINGO_EXCLUDE_APPS = ('debug_toolbar',)
-If a template is in the *app folder*, `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``
+If a template is in the *app folder*, ``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``.
+
+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

0 comments on commit 1dc0e0b

Please sign in to comment.