======================
Ella's template schema
======================

Template hierarchies
====================

All template names throughout Ella are designed in such a way that would allow
for easy overriding for specific objects. For example you can easily and
directly specify how a list of artciles in certain category (one with slug
`some-category`) should look like just by creating a template called::

    page/category/some-category/content_type/articles.article/listing.html


Common templates
----------------

The Ella's core functionality use following templates:


Object detail:
    * page/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/``SLUG``/object.html
    * page/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/object.html
    * page/category/``CATEGORY-SLUG``/object.html
    * page/content_type/``APP_LABEL.MODEL``/object.html
    * page/object.html

Object listing:
    * page/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/listing.html
    * page/category/``CATEGORY-SLUG``/listing.html
    * page/content_type/``APP_LABEL.MODEL``/listing.html
    * page/listing.html

Category homepage:
    * page/category/``CATEGORY-SLUG``/category.html
    * page/category.html

Where:

| ``CATEGORY-SLUG``: slug of the category
| ``APP_LABEL.MODEL``: name of the relevant model
| ``SLUG``: slug of the model (if applicable)

This hierarchy ensures that the most specific template for a given task is
used. In some cases, such as listing all objects from a given category, not
all steps of the hierrchy are applicable
(``page/content_type/APP_LABEL.MODEL/listing.html`` in this example).


App-specific templates
----------------------

Many Ella application have their own set of templates, which should follow the
same pattern. For example here is how ``ella.comments`` look for its form
template:


    * page/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/``SLUG``/comments/form.html
    * page/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/comments/form.html
    * page/category/``CATEGORY-SLUG``/comments/form.html
    * page/content_type/``APP_LABEL.MODEL``/comments/form.html
    * page/comments/form.html

Object manifestation in HTML
============================

When an object is used inside a page, it is usually done via a ``box``
templatetag. This tag takes a name and either a model name and some identifier to look up
the object in the database (``slug``, ``pk``, etc.) or variable to look up in
the context. The object is then rendered in a template with a corresponding
name. The lookup hierarchy for boxes is:

    * box/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/``SLUG``/BOX_NAME.html
    * box/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/BOX_NAME.html
    * box/category/``CATEGORY-SLUG``/content_type/``APP_LABEL.MODEL``/box.html
    * box/content_type/``APP_LABEL.MODEL``/``SLUG``/BOX_NAME.html
    * box/content_type/``APP_LABEL.MODEL``/BOX_NAME.html
    * box/content_type/``APP_LABEL.MODEL``/box.html
    * box/BOX_NAME.html
    * box/box.html

