[2474] Document the base.html and page.html files

ckan · May 29, 2012 · d11642f · d11642f
1 parent 9124f56
commit d11642f
Show file tree

Hide file tree

Showing 2 changed files with 112 additions and 1 deletion.
diff --git a/ckan/templates/base.jinja.html b/ckan/templates/base.jinja.html
@@ -1,20 +1,92 @@
+{# Allows the DOCTYPE to be set on a page by page basis #}
 {% block doctype %}<!DOCTYPE html>{% endblock %}
+
+{# Allows custom attributes to be added to the <html> tag #}
 {% block htmltag %}<html lang="en-gb">{% endblock %}
+
+  {# Allows custom attributes to be added to the <head> tag #}
   {% block headtag %}<head>{% endblock %}
+    {#
+    Add custom meta tags to the page. Call super() to get the default tags
+    such as charset, viewport and generator.
+
+    Example:
+
+    {% block meta %}
+      {{ super() }}
+      <meta name="description" value="My website description" />
+    {% endblock %}
+
+    #}
     {% block meta %}
       <meta charset="utf-8" />
     {% endblock %}
-    <title>{% if title %}{{title}} - {% endif %}CKAN</title>
+
+    {#
+    Add a custom title to the page by extending the title block. Call super()
+    to get the default page title.
+
+    Example:
+
+      {% block title %}My Subtitle - {{ super() }}{% endblock %}
+
+    #}
+    <title>{% block title %}CKAN{% title %}</title>
+
+    {#
+    The links block allows you to add additonal content before the stylesheets
+    such as rss feeds and favicons in the same way as the meta block.
+    #}
     {% block links %}
       <link rel="shortcut icon" href="/base/images/ckan.ico" />
     {% endblock %}
+
+    {#
+    The styles block allows you to add additonal stylesheets to the page in
+    the same way as the meta block. Use super() to include the default
+    stylesheets before or after your own.
+
+    Example:
+
+      {% block styles %}
+        {{ super() }}
+        <link rel="stylesheet" href="/base/css/custom.css" />
+      {% endblock %}
+    #}
     {% block styles %}
       <link rel="stylesheet/less" href="/base/less/main.less" />
       <script src="/base/test/vendor/less.js"></script>
     {% endblock %}
   </head>
+
+  {# Allows custom attributes to be added to the <body> tag #}
   {% block bodytag %}<body>{% endblock %}
+
+    {#
+    The page block allows you to add content to the page. Most of the time it is
+    recommended that you extend one of the page.html templates in order to get
+    the site header and footer. If you need a clean page then this is the
+    block to use.
+
+    Example:
+
+      {% block page %}
+        <div>Some other page content</div>
+      {% endblock %}
+    #}
     {% block page %}{% endblock %}
+
+    {#
+    The scripts block allows you to add additonal scripts to the page. Use the
+    super() function to load the default scripts before/after your own.
+
+    Example:
+
+      {% block script %}
+        {{ super() }}
+        <script src="/base/js/custom.js"></script>
+      {% endblock %}
+    #}
     {% block scripts %}{% endblock %}
   </body>
 </html>
diff --git a/ckan/templates/page.jinja.html b/ckan/templates/page.jinja.html
@@ -1,9 +1,17 @@
 {% extends "base.jinja.html" %}
 
 {% block page %}
+
+  {#
+  Override the header on a page by page basis by extending this block. If
+  making sitewide header changes it is preferable to override the header.html
+  file.
+  #}
   {% block header %}
     {% include "header.jinja.html" %}
   {% endblock %}
+
+  {# The content block allows you to replace the content of the page if needed #}
   {% block content %}
     <div role="main">
       <div class="container">
@@ -13,19 +21,50 @@
             {% block actions %}{% endblock %}
           </div>
         {% endblock %}
+
         {% block primary %}
           <div class="primary">
+            {#
+            The primary_content block can be used to add content to the page.
+            This is the main block that is likely to be used within a template.
+
+            Example:
+
+              {% block primary_content %}
+                <h1>My page content</h1>
+                <p>Some content for the page</p>
+              {% endblock %}
+            #}
             {% block primary_content %}{% endblock %}
           </div>
         {% endblock %}
+
         {% block secondary %}
           <aside class="secondary">
+            {#
+            The secondary_content block can be used to add content to the
+            sidebar of the page. This is the main block that is likely to be
+            used within a template.
+
+            Example:
+
+              {% block secondary_content %}
+                <h2>A sidebar item</h2>
+                <p>Some content for the item</p>
+              {% endblock %}
+            #}
             {% block secondary_content %}{% endblock %}
           </aside>
         {% endblock %}
       </div>
     </div>
   {% endblock %}
+
+  {#
+  Override the footer on a page by page basis by extending this block. If
+  making sitewide header changes it is preferable to override the footer.html
+  file.
+  #}
   {% block footer %}
     {% include "footer.jinja.html" %}
   {% endblock %}