From 6871387671c4e8ecc9e070c76a528908ed5c8d8b Mon Sep 17 00:00:00 2001 From: Kyle Fuller Date: Thu, 1 Dec 2016 16:20:28 +0000 Subject: [PATCH] feat(docs): Document template inheritence --- docs/builtins.rst | 11 ++++++ docs/templates.rst | 88 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) diff --git a/docs/builtins.rst b/docs/builtins.rst index 90af0af..2935c86 100644 --- a/docs/builtins.rst +++ b/docs/builtins.rst @@ -217,9 +217,20 @@ the template. ``extends`` ~~~~~~~~~~~ +Extends the template from a parent template. + +.. code-block:: html+django + + {% extends "base.html" %} + +See :ref:`template-inheritance` for more information. + ``block`` ~~~~~~~~~ +Defines a block that can be overridden by child templates. See +:ref:`template-inheritance` for more information. + .. _built-in-filters: Built-in Filters diff --git a/docs/templates.rst b/docs/templates.rst index 4aafa4c..bd7d5e1 100644 --- a/docs/templates.rst +++ b/docs/templates.rst @@ -75,3 +75,91 @@ To comment out part of your template, you can use the following syntax: .. code-block:: html+django {# My comment is completely hidden #} + +.. _template-inheritance: + +Template inheritance +-------------------- + +Template inheritance allows the common components surrounding individual pages +to be shared across other templates. You can define blocks which can be +overidden in any child template. + +Let's take a look at an example. Here is our base template (``base.html``): + +.. code-block:: html+django + + + + {% block title %}Example{% endblock %} + + + + + +
+ {% block content %}{% endblock %} +
+ + + +This example declares three blocks, ``title``, ``sidebar`` and ``content``. We +can use the ``{% extends %}`` template tag to inherit from out base template +and then use ``{% block %}`` to override any blocks from our base template. + +A child template might look like the following: + +.. code-block:: html+django + + {% extends "base.html" %} + + {% block title %}Notes{% endblock %} + + {% block content %} + {% for note in notes %} +

{{ note }}

+ {% endfor %} + {% endblock %} + +Since our child template doesn't declare a sidebar block. The original sidebar +from our base template will be used. Depending on the content of ``notes`` our +template might be rendered like the following: + +.. code-block:: html + + + + Notes + + + + + +
+

Pick up food

+

Do laundry

+
+ + + +You can use as many levels of inheritance as needed. One common way of using +inheritance is the following three-level approach: + +* Create a ``base.html`` template that holds the main look-and-feel of your site. +* Create a ``base_SECTIONNAME.html`` template for each “section” of your site. + For example, ``base_news.html``, ``base_news.html``. These templates all + extend ``base.html`` and include section-specific styles/design. +* Create individual templates for each type of page, such as a news article or + blog entry. These templates extend the appropriate section template.