[#847] Break up theming tutorial into multiple pages

CHANGELOG.rst

@@ -194,7 +194,7 @@ Organizations based authorization (see :doc:`authorization`):
  * New authorization ini file options
 
 
-New frontend (see :doc:`theming`):
+New frontend (see :doc:`theming/index`):
  CKAN's frontend has been completely redesigned, inside and out. There is
  a new default theme and the template engine has moved from Genshi to
  Jinja2. Any custom templates using Genshi will need to be updated, although

ckan/plugins/interfaces.py

@@ -770,7 +770,7 @@ def read_template(self):
 
         If the user requests the dataset in a format other than HTML
         (CKAN supports returning datasets in RDF or N3 format by appending .rdf
-        or .n3 to the dataset read URL, see :doc:`linked-data-and-rdf`) then
+        or .n3 to the dataset read URL, see :doc:`/linked-data-and-rdf`) then
         CKAN will try to render
         a template file with the same path as returned by this function,
         but a different filename extension, e.g. ``'package/read.rdf'``.

ckan/plugins/toolkit.py

@@ -216,7 +216,7 @@ def _initialize(self):
     def _render_snippet(cls, template, data=None):
         '''Render a template snippet and return the output.
 
-        See :doc:`/theming`.
+        See :doc:`/theming/index`.
 
         '''
         data = data or {}
@@ -266,7 +266,7 @@ def _add_resource(cls, path, name):
         Fanstatic libraries are directories containing static resource files
         (e.g. CSS, JavaScript or image files) that can be accessed from CKAN.
 
-        See :doc:`/theming` for more details.
+        See :doc:`/theming/index` for more details.
 
         '''
         # we want the filename that of the function caller but they will

doc/conf.py

@@ -58,6 +58,10 @@
 .. |javascript| replace:: JavaScript
 .. |apache| replace:: Apache
 
+.. _Jinja2: http://jinja.pocoo.org/
+.. _CKAN front page: http://127.0.0.1:5000
+.. _bootstrap: http://getbootstrap.com/2.3.2/
+
 '''
 
 # Add any Sphinx extension module names here, as strings. They can be extensions

doc/configuration.rst

@@ -655,7 +655,7 @@ Format tips:
 * the format is Markdown
 
 .. note:: Whilst the default text is translated into many languages (switchable in the page footer), the text in this configuration option will not be translatable.
-          For this reason, it's better to overload the snippet in ``home/snippets/about_text.html``. For more information, see :doc:`theming`.
+          For this reason, it's better to overload the snippet in ``home/snippets/about_text.html``. For more information, see :doc:`theming/index`.
 
 .. _ckan.main_css:
 
@@ -951,7 +951,7 @@ Example::
 
 To customise the display of CKAN you can supply replacements for the Genshi template files. Use this option to specify where CKAN should look for additional templates, before reverting to the ``ckan/templates`` folder. You can supply more than one folder, separating the paths with a comma (,).
 
-For more information on theming, see :doc:`theming`.
+For more information on theming, see :doc:`theming/index`.
 
 .. _extra_public_paths:
 
@@ -964,7 +964,7 @@ Example::
 
 To customise the display of CKAN you can supply replacements for static files such as HTML, CSS, script and PNG files. Use this option to specify where CKAN should look for additional files, before reverting to the ``ckan/public`` folder. You can supply more than one folder, separating the paths with a comma (,).
 
-For more information on theming, see :doc:`theming`.
+For more information on theming, see :doc:`theming/index`.
 
 .. end_config-theming
 

doc/index.rst

@@ -19,7 +19,7 @@ advanced documentation last:
   beyond those that just work out of the box.  These are for **sysadmins** who
   want to learn how to manage and get more out of their CKAN site.
 
-* :doc:`extensions/index`, :doc:`theming` and :doc:`api` are advanced docs
+* :doc:`extensions/index`, :doc:`theming/index` and :doc:`api` are advanced docs
   for **developers** who want to develop an extension, theme or API app using
   CKAN.
 
@@ -39,7 +39,7 @@ advanced documentation last:
    getting-started
    features
    extensions/index
-   theming
+   theming/index
    api
    contributing
    test

doc/tag-vocabularies.rst

@@ -65,6 +65,6 @@ To add a tag vocabulary to a site, a CKAN sysadmin must:
 
 3. Provide custom dataset templates to display the new field to users when
    adding, updating or viewing datasets in the CKAN web interface.
-   See :doc:`theming`.
+   See :doc:`theming/index`.
 
 See ``ckanext/example_idatasetform`` for a working example of these steps.

doc/theming/css.rst

@@ -0,0 +1,63 @@
+======================
+Customizing CKAN's CSS
+======================
+
+Extensions can add their own CSS files to modify or extend CKAN's default CSS.
+Create an ``example_theme.css`` file in your extension's ``public`` directory::
+
+    ckanext-example_theme/
+      public/
+        example_theme.css
+
+Add this CSS into the ``example_theme.css`` file, to change the color of CKAN's
+"account masthead" (the bar across the top of the site that shows the logged-in
+user's account info):
+
+.. literalinclude:: /../ckanext/example_theme/v12_custom_css/public/example_theme.css
+
+If your restart the development web server (kill the server using Ctrl-c, then
+run the ``paster serve`` command again) you should be able to open this file at
+http://127.0.0.1:5000/example_theme.css in a web browser.
+
+To make CKAN use our custom CSS we need to override the ``base.html`` template,
+this is the base template which the templates for all CKAN pages extend, so if
+we include a CSS file in this base template then the file will be included in
+every page of your CKAN site. Create the file::
+
+    ckanext-example_theme/
+      templates/
+        base.html
+
+and put this Jinja code in it:
+
+.. literalinclude:: /../ckanext/example_theme/v12_custom_css/templates/base.html
+
+The default ``base.html`` template defines a ``styles`` block which can be
+extended to link to custom CSS files (any code in the styles block will appear
+in the ``<head>`` of the HTML page).
+
+Restart the development web server, and you should see the background color of
+the account masthead change. This custom color should appear on all pages of
+your CKAN site.
+
+Now that we have CKAN using our CSS file, we can add more CSS rules to the file
+and customize CKAN's CSS as much as we want. There's nothing special about CSS
+in CKAN, you just use the usual tools and techniques to explore and hack the
+CSS.
+
+.. todo:: Link to some tools?
+
+   e.g. Firefox inspector etc (or Chrome? Firebug?)
+
+   e.g. Some online CSS reference.
+
+Let's add a bit more code to our ``example_theme.css`` file. This CSS
+implements a partial imitation of the `datahub.io <http://datahub.io/>`_ theme
+(circa 2013):
+
+.. literalinclude:: /../ckanext/example_theme/v13_more_custom_css/public/example_theme.css
+
+.. todo::
+
+   We use LESS for the CKAN core CSS. Do we want to mention that here?
+

doc/theming/index.rst

@@ -0,0 +1,31 @@
+=======
+Theming
+=======
+
+The CKAN web interface's HTML, CSS and JavaScript is fully customizable by
+creating a CKAN theme.
+If you just want to do some simple customizations such as changing the title
+of your CKAN site, or making some small CSS customizations,
+:doc:`/getting-started` documents some simple configuration settings you can
+use.
+If you want more control, follow the tutorials below to learn how to develop
+your custom CKAN theme.
+
+
+.. note::
+
+  Before you can start developing a CKAN theme, you’ll need a working source
+  install of CKAN on your system. If you don't have a CKAN source install
+  already, follow the instructions in :doc:`/install-from-source` before
+  continuing.
+
+.. toctree::
+   :maxdepth: 2
+
+   templates
+   static-files
+   css
+   javascript
+   jinja-tags
+   variables-and-functions
+   template-helper-functions

doc/theming/javascript.rst

@@ -0,0 +1,120 @@
+=============================
+Customizing CKAN's JavaScript
+=============================
+
+.. todo:: Link to an introductory JavaScript tutorial.
+
+.. todo:: Introduce the example we're doing here: starring datasets using a
+     custom dataset_star action (also need the code to add this action).
+
+.. todo:: Explain that Bootstrap's JavaScript features can be used just by CSS.
+
+
+--------------------------------
+Initializing a JavaScript module
+--------------------------------
+
+To get CKAN to call some custom JavaScript code, we need to:
+
+1. Implement a |javascript| module, and register it with CKAN.
+   Create the file ``ckanext-example_theme/fanstatic/favorite.js``, with these
+   contents:
+
+   .. literalinclude:: /../ckanext/example_theme/v14_initialize_a_javascript_module/fanstatic/favorite.js
+
+   This bit of |javascript| calls the ``ckan.module()`` function to register a
+   new JavaScript module with CKAN. ``ckan.module()`` takes two arguments: the
+   name of the module being registered (``'favorite'`` in this example) and a
+   function that returns the module itself. The function takes two arguments,
+   which we'll look at later. The module is just a |javascript| object with a
+   single attribute, ``initialize``, whose value is a function that CKAN will
+   call to initialize the module. In this example, the initialize function just
+   prints out a confirmation message - this |javascript| module doesn't do
+   anything interesting yet.
+
+2. Include the |javascript| module in a page, using Fanstatic, and apply it to
+   one or more HTML elements on that page. We'll override CKAN's
+   ``package_item.html`` template snippet to insert our module whenever a
+   package is rendered as part of a list of packages (for example, on the
+   dataset search page). Create the file
+   ``ckanext-example_theme/templates/snippets/package_item.html`` with these
+   contents:
+
+   .. literalinclude:: /../ckanext/example_theme/v14_initialize_a_javascript_module/templates/snippets/package_item.html
+
+   .. todo:: Link to something about HTML data-* attributes.
+
+   If you now restart the development server and open
+   http://127.0.0.1:5000/dataset in your web browser, you should see an
+   extra "star this dataset" button next to each dataset shown. If you open a
+   |javascript| console in your browser, you should see the message that your
+   module has printed out.
+
+   .. todo:: Link to something about JavaScript consoles.
+
+   If you have more than one dataset on your page, you'll see the module's
+   message printed once for each dataset. The ``package_item.html`` template
+   snippet is rendered once for each dataset that's shown in the list, and
+   CKAN creates a new instance of your |javascript| module for each dataset.
+   If you view the source of your page, however, you'll see that
+   ``favorite.js`` is only included with a ``<script>`` tag once. Fanstatic
+   is smart enough to deduplicate resources.
+
+   .. note:: |javascript| modules *must* be included as Fanstatic resources,
+      you can't add them to a ``public`` directory and include them using your
+      own ``<script>`` tags.
+
+
+--------------------
+Responding to events
+--------------------
+
+To get our |javascript| module to do something more interesting, we'll use its
+initialize function to register some event handler functions which we'll then
+use to do some actions in response to events such as mouse clicks. Edit your
+``favorite.js`` file to look like this:
+
+.. Link to some JavaScript tutorial?
+
+   JavaScript modules are the core - every javascripted object should be a
+   module. Small, isolated components that can be easily tested. They should
+   not use any global objects, all functionality provided to them via a sandbox
+   object.
+
+   A module is a JavaScript object with an initialize() and a teardown()
+   method.
+
+   Initialize a module with a data-module attribute:
+     <select name="format" data-module="autocomplete"></select>
+
+   Or apparently you can also use {% resource %}? Or you have to use resource?
+
+   "favorite" module goes in favorite.js file.
+
+   The idea is that the HTML element should still work fine is JavaScript is
+   disabled - e.g. use form submission instead of XHR request.
+
+   You can pass "options objects" with further data-module-* attributes.
+
+   The modules are initialized "on DOM ready", each module's initialize()
+   method is called.
+
+   this.sandbox.jQuery - access jQuery methods
+   this.sandbox.translte() - i18n
+   (or these are the jQuery and _ params of your module function)
+
+   pub/sub for sending messages between modules:
+   this.sandbox.publish/subscribe/unsubscribe
+
+   this.sandbox.client should be used to make XHR requests to the CKAN API
+   (not jQuery.ajax())
+
+   i18n: this.sandbox.translate(), supports %(name)s, including plurals.
+   The options() method of each module should set all strings to be i18n'd?
+   Then other code uses this.18n() to retrieve them.
+
+   If not CKAN specific, module functionality should be packaged up in jQuery
+   plugins.
+
+   Testing.
+

doc/theming/jinja-tags.rst

@@ -0,0 +1,5 @@
+============================
+Custom Jinja2 tags reference
+============================
+
+.. todo::