From 0d6a0ec0fe84f4b5d6723a69035d40d8c923e65e Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Thu, 28 Nov 2013 14:34:07 +0100 Subject: [PATCH] [#847] Various tweaks to theming docs --- .../templates/home/layout1.html | 1 - doc/theming/best-practices.rst | 29 ++++++++-- doc/theming/fanstatic.rst | 2 +- doc/theming/static-files.rst | 7 +-- doc/theming/templates.rst | 19 +++++-- doc/theming/variables-and-functions.rst | 54 ++++++++++++++----- 6 files changed, 85 insertions(+), 27 deletions(-) diff --git a/ckanext/example_theme/v08_custom_helper_function/templates/home/layout1.html b/ckanext/example_theme/v08_custom_helper_function/templates/home/layout1.html index 4358cea5ac2..43b6d131746 100644 --- a/ckanext/example_theme/v08_custom_helper_function/templates/home/layout1.html +++ b/ckanext/example_theme/v08_custom_helper_function/templates/home/layout1.html @@ -13,6 +13,5 @@

Most popular groups

  • {{ group.display_name }}
    • {% endfor %} - {# End of most popular groups. #} {% endblock %} diff --git a/doc/theming/best-practices.rst b/doc/theming/best-practices.rst index e50c165f32e..c0fd7555deb 100644 --- a/doc/theming/best-practices.rst +++ b/doc/theming/best-practices.rst @@ -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 ` 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()`` ----------------- @@ -12,6 +26,7 @@ like ````. 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()`` ------------------------------- @@ -19,16 +34,20 @@ 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 @@ -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. diff --git a/doc/theming/fanstatic.rst b/doc/theming/fanstatic.rst index c5fb60a8f4f..7d458668fd4 100644 --- a/doc/theming/fanstatic.rst +++ b/doc/theming/fanstatic.rst @@ -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 ``