=======================
Creating a new template
=======================

This is a brief tutorial covering the basics of building a common
template.

Extending a base template
-------------------------

Firstly we need to extend a parent template to provide us with some
basic page structure. This can be any other HTML page however the most
common one is ``page.html`` which provides the full CKAN theme including
header and footer.

::

    {% extends "page.html" %}

The ``page.html`` template provides numerous blocks that can be
extended. It’s worth spending a few minutes getting familiar with what’s
available. The most common blocks that we’ll be using are those ending
with “content”.

-  ``primary_content``: The main content area of the page.
-  ``secondary_content``: The secondary content (sidebar) of the page.
-  ``breadcrumb_content``: The contents of the breadcrumb navigation.
-  ``actions_content``: The content of the actions bar to the left of
   the breadcrumb.

Primary Content
---------------

For now we’ll add some content to the main content area of the page.

::

    {% block primary_content %}
      {{ super() }}

      {% block my_content %}
        <h2>{{ _('This is my content heading') }}</h2>
        <p>{{ _('This is my content') }}</p>
      {% endblock %}
    {% endblock %}

Notice we’ve wrapped our own content in a block. This allows other
templates to extend and possibly override this one and is extremely
useful for making a them more customisable.

Secondary Content
-----------------

Secondary content usually compromises of reusable modules which are
pulled in as snippets. Snippets are also very useful for keeping the
templates clean and allowing theme extensions to override them.

::

    {% block primary_content %}
      {{ super() }}

      {% block my_sidebar_module %}
        {% snippet "snippets/my-sidebar-module.html" %}
      {% endblock %}
    {% endblock %}

Breadcrumb and Actions
----------------------

There is a consistent breadcrumb running through all the pages and often
it is useful to provide additional actions that a related to the page.

::

    {% block breadcrumb_content %}
      <li class="active">{% link_for _('Viewing Dataset'), named_route=pkg.type ~ '.read', id=pkg.id %}</li>
    {% endblock %}

    {% block actions_content %}
      {{ super() }}
      <li class="active">{% link_for _('New Dataset'), named_route='dataset.new', class_='btn', icon='plus' %}</li>
    {% endblock %}

Scripts and Stylesheets
-----------------------

Currently scripts and stylesheets can be added by using the
``{% asset %}`` tag which manages script loading for us.

::

{% asset 'my-extension/main-css' %}
{% asset 'my-extension/main-js' %}


Summary
-------

And that’s about all there is to it be sure to check out ``base.html``
and ``page.html`` to see all the tags available for extension.