Breaking docs up into smaller pieces

2010-04-18 13:35:40 +02:00 · 2010-04-18 13:35:40 +02:00 · 123a1ad019
commit 123a1ad019
parent 764b4e4f7d
8 changed files with 443 additions and 445 deletions
--- a/docs/patterns/templateinheritance.rst
+++ b/docs/patterns/templateinheritance.rst
@ -0,0 +1,69 @@
+.. _template-inheritance:
+
+Template Inheritance
+====================
+
+The most powerful part of Jinja is template inheritance. Template inheritance
+allows you to build a base "skeleton" template that contains all the common
+elements of your site and defines **blocks** that child templates can override.
+
+Sounds complicated but is very basic. It's easiest to understand it by starting
+with an example.
+
+
+Base Template
+-------------
+
+This template, which we'll call ``layout.html``, defines a simple HTML skeleton
+document that you might use for a simple two-column page. It's the job of
+"child" templates to fill the empty blocks with content:
+
+.. sourcecode:: html+jinja
+
+    <!doctype html>
+    <html>
+      <head>
+        {% block head %}
+        <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
+        <title>{% block title %}{% endblock %} - My Webpage</title>
+        {% endblock %}
+      </head>
+    <body>
+      <div id="content">{% block content %}{% endblock %}</div>
+      <div id="footer">
+        {% block footer %}
+        &copy; Copyright 2010 by <a href="http://domain.invalid/">you</a>.
+        {% endblock %}
+      </div>
+    </body>
+
+In this example, the ``{% block %}`` tags define four blocks that child templates
+can fill in. All the `block` tag does is to tell the template engine that a
+child template may override those portions of the template.
+
+Child Template
+--------------
+
+A child template might look like this:
+
+.. sourcecode:: html+jinja
+
+    {% extends "layout.html" %}
+    {% block title %}Index{% endblock %}
+    {% block head %}
+      {{ super() }}
+      <style type="text/css">
+        .important { color: #336699; }
+      </style>
+    {% endblock %}
+    {% block content %}
+      <h1>Index</h1>
+      <p class="important">
+        Welcome on my awesome homepage.
+    {% endblock %}
+
+The ``{% extends %}`` tag is the key here. It tells the template engine that
+this template "extends" another template.  When the template system evaluates
+this template, first it locates the parent.  The extends tag must be the
+first tag in the template.  To render the contents of a block defined in
+the parent template, use ``{{ super() }}``.