Skip to content

Commit

Permalink
[#847] Various tweaks to theming docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Sean Hammond committed Nov 28, 2013
1 parent 9972390 commit 0d6a0ec
Show file tree
Hide file tree
Showing 6 changed files with 85 additions and 27 deletions.
1 change: 0 additions & 1 deletion ckanext/example_theme/v08_custom_helper_function/templates/home/layout1.html
View file
Expand Up @@ -13,6 +13,5 @@ <h3>Most popular groups</h3>
<li>{{ group.display_name }}</li>
{% endfor %}
</ul>
{# End of most popular groups. #}

{% endblock %}
29 changes: 24 additions & 5 deletions doc/theming/best-practices.rst
View file
Expand Up @@ -2,6 +2,20 @@
Best practices for writing CKAN themes
======================================

.. _don't use c:

---------------
Don't use ``c``
---------------

As much as possible, avoid accessing the Pylons template context :py:data:`c`
(or :py:data:`tmpl_context`). Use
:doc:`template helper functions <template-helper-functions>` instead.
You can use the :py:class:`~ckan.plugins.interfaces.ITemplateHelpers` plugin
interface to add custom helper functions, see
:ref:`custom template helper functions`.


-----------------
Use ``url_for()``
-----------------
Expand All @@ -12,23 +26,28 @@ like ``<a href="/dataset">``. Links created with
:py:func:`~ckan.lib.helpers.url_for` will update themselves if the URL routing
changes in a new version of CKAN, or if a plugin changes the URL routing.


-------------------------------
Use ``_()`` and ``ungettext()``
-------------------------------

Always use :py:func:`_` (or, if pluralizaton is needed, :py:func:`ungettext`)
to mark user-visible strings for localization.


-----------------------------------------------------------------
Helper function names should begin with the name of the extension
-----------------------------------------------------------------

Namespacing helper functions in this way avoids accidentally overriding, or
being overriden by, a core helper function, or a helper function from another
extension. For example::
extension. For example:

.. literalinclude:: /../ckanext/example_theme/v08_custom_helper_function/plugin.py
:pyobject: ExampleThemePlugin.get_helpers

example_theme_most_popular_groups

.. _snippet filenames best practice:

-------------------------------------------------------------
Snippet filenames should begin with the name of the extension
Expand All @@ -38,15 +57,15 @@ Namespacing snippets in this way avoids accidentally overriding, or being
overridden by, a core snippet, or a snippet from another extension.
For example::

ckanext-example_theme/ckanext/example_theme/templates/snippets/example_theme_most_popular_groups.html
snippets/example_theme_most_popular_groups.html


--------------------------------------------
Use ``{% snippet %}``, not ``{% include %}``
--------------------------------------------

Always use CKAN's custom ``{% snippet %}`` instead of Jinja's default
Always use CKAN's custom ``{% snippet %}`` tag instead of Jinja's default
``{% include %}`` tag. Snippets can only access certain global variables, and
any variables explicitly passed to them by the calling template. They don't
have access to the full context of the calling template, as included files do.
This makes snippets much easier to debug.
This makes snippets more reusable, and much easier to debug.
2 changes: 1 addition & 1 deletion doc/theming/fanstatic.rst
View file
Expand Up @@ -49,7 +49,7 @@ to serve the CSS file with Fanstatic.
.. note::

You can put ``{% resource %}`` tags anywhere in any template, and Fanstatic
will insert and necessary ``<style>`` and ``<script>`` tags to include your
will insert the necessary ``<style>`` and ``<script>`` tags to include your
CSS and |javascript| files and their dependencies in the right places in
the HTML output (CSS files in the HTML ``<head>``, |javascript| files at
the bottom of the page).
Expand Down
7 changes: 4 additions & 3 deletions doc/theming/static-files.rst
View file
Expand Up @@ -16,7 +16,7 @@ to use our file as the promoted image on the front page.

If you're adding CSS files consider using Fanstatic instead of
:ref:`extra_public_paths`, to take advantage of extra features.
See :doc:`css`. If you're adding |javascript| modules you have to
See :doc:`fanstatic`. If you're adding |javascript| modules you have to
use Fanstatic, see :doc:`javascript`.

First, create a ``public`` directory in your extension with a
Expand Down Expand Up @@ -68,5 +68,6 @@ tag itself, pointing it at our custom static image file:
.. literalinclude:: /../ckanext/example_theme/v12_extra_public_dir/templates/home/snippets/promoted.html
:start-after: {# Replace the promoted image. #}

If you now reload the `CKAN front page`_ in your browser, you should see the
promoted image replaced with our custom one.
If you now restart the development web server and reload the `CKAN front page`_
in your browser, you should see the promoted image replaced with our custom
one.
19 changes: 15 additions & 4 deletions doc/theming/templates.rst
View file
Expand Up @@ -137,6 +137,8 @@ Set :ref:`debug` to ``true`` in your |development.ini| file::
# WARNING: *THIS SETTING MUST BE SET TO FALSE ON A PRODUCTION ENVIRONMENT*
debug = true

.. _debug footer:

Reload the `CKAN front page`_ in your browser, and you should see a *Debug*
link in the footer at the bottom of the page. Click on this link to open the
debug footer. The debug footer displays various information useful for CKAN
Expand Down Expand Up @@ -268,7 +270,7 @@ any template file:

{{ a_variable_that_does_not_exist.an_attribute_that_does_not_exist }}

See the `Jinja2 docs <http://jinja.pocoo.org/docs/templates/#variables>`_
See the `Jinja2 variables docs <http://jinja.pocoo.org/docs/templates/#variables>`_
for details.

.. note::
Expand Down Expand Up @@ -371,9 +373,9 @@ template with its own code by using ``{% block %}``. Create the file
.. literalinclude:: /../ckanext/example_theme/v05_block/templates/home/layout1.html

This file extends the default ``layout1.html`` template, and overrides the
``featured_group`` block. Reload the `CKAN front page`_ in your browser. You
should see that the featured groups section of the page has been replaced, but
the rest of the page remains intact.
``featured_group`` block. Restart the development web server and reload the
`CKAN front page`_ in your browser. You should see that the featured groups
section of the page has been replaced, but the rest of the page remains intact.

.. note::

Expand Down Expand Up @@ -582,6 +584,14 @@ number of CKAN's template helper functions:
:py:func:`ungettext` function to mark the message for translation with
localized handling of plural forms.

The code also accesses the attributes of each group: ``{{ group.name }}`,
``{{ group.display_name }}``, ``{{ group.description }}``,
``{{ group.packages }}``, etc. To see what attributes a group or any other CKAN
object (packages/datasets, organizations, users...) has, you can use
:doc:`CKAN's API </api>` to inspect the object. For example to find out what
attributes a group has, call the :py:func:`~ckan.logic.action.get.group_show`
function.

Now edit your |layout1.html| file and change it to use our new snippet instead
of the default one:

Expand All @@ -600,6 +610,7 @@ of the default one:
To avoid unintended conflicts, we recommend that snippet filenames begin
with the name of the extension they belong to, e.g.
``snippets/example_theme_*.html``.
See :ref:`snippet filenames best practice`.

.. note::

Expand Down
54 changes: 41 additions & 13 deletions doc/theming/variables-and-functions.rst
View file
@@ -1,29 +1,66 @@
.. include:: ./substitutions.rst

==============================================
Variables and functions available to templates
==============================================

The following global variables and functions are available to all CKAN
templates in their top-level namespace:

.. py:data:: c
.. note::

In addition to the global variables listed below, each template also has
access to variables from a few other sources:

* Any extra variables explicitly passed into a template by the controller
that rendered the template will also be available to that template, in its
top-level namespace. Any variables explicitly added to the template
context variable :py:data:`c` will also be available to the template as
attributes of :py:data:`c`.

To see which additional global variables and context attributes are
available to a given template, use CKAN's
:ref:`debug footer <debug footer>`.

* Any variables explicitly passed into a template snippet in the calling
``{% snippet %}`` tag will be available to the snippet in its top-level
namespace. To see these variables, use the
:ref:`debug footer <debug footer>`.

* Jinja2 also makes a number of filters, tests and functions available in
each template's global namespace. For a list of these, see the
`Jinja2 docs`_.

.. py:data:: tmpl_context
The `Pylons template context object <http://pylonsbook.com/en/1.0/exploring-pylons.html?highlight=template%20context#context-object>`_,
a thread-safe object that the application can store request-specific
variables against without the variables associated with one HTTP request
getting confused with variables from another request.

``tmpl_context`` is usually abbreviated to ``c`` (an alias).

Using ``c`` in CKAN is discouraged, use template helper functions instead.
See :ref:`don't use c`.

``c`` is not available to snippets.

.. py:data:: c
An alias for :py:data:`tmpl_context`.

.. py:data:: app_globals
The `Pylons App Globals object <http://pylonsbook.com/en/1.0/exploring-pylons.html?highlight=template%20context#app-globals-object>`_,
an instance of the :py:class:`ckan.lib.app_globals.Globals` class.
The application can store request-independent variables
against the ``app_globals`` object.. Variables stored against
against the ``app_globals`` object. Variables stored against
``app_globals`` are shared between all HTTP requests.

.. py:data:: g
An alias for :py:data:`app_globals`.

.. py:data:: h
CKAN's :ref:`template helper functions <template helper functions>`, plus
Expand Down Expand Up @@ -51,7 +88,7 @@ templates in their top-level namespace:
which contains information stored in the user's currently active session
cookie.

.. py:function:: _(value)
.. py:function:: _()
The `pylons.i18n.translation.ugettext(value) <http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/modules/i18n_translation.html?highlight=ugettext#pylons.i18n.translation.ugettext>`_ function:

Expand All @@ -62,7 +99,7 @@ templates in their top-level namespace:

_('This should be in lots of languages')

.. py:function:: N_(value)
.. py:function:: N_()
The `pylons.i18n.translation.gettext_noop(value) <http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/modules/i18n_translation.html?highlight=gettext_noop#pylons.i18n.translation.gettext_noop>`_ function:

Expand Down Expand Up @@ -113,12 +150,3 @@ templates in their top-level namespace:

.. todo:: Remove this? Doesn't appear to be used and doesn't look like
something we want.

In addition to the above, any variables explicitly passed into a template by a
controller action method when it calls ``render()`` will also be available to
that template, in its top-level namespace.

Any variables explicitly passed into a template snippet in the calling ``{%
snippet %}`` tag will be available to the snippet in its top-level namespace,

.. todo:: Add links to the default stuff that Jinja provides to all templates.

0 comments on commit 0d6a0ec

Please sign in to comment.