A tour of the templates

From OpenHatch wiki

This is a page about improving or modifying OpenHatch.

We call that "Hacking OpenHatch," and there is a whole category of pages about that.


The OpenHatch site has a lot of Django template files. This page explains what they are and how they work together.

Background knowledge

This page uses the following terminology:

  • A template file is a file (e.g., mysite/base/templates/base/base.html) that usually ends in ".html")
  • Our templates make extensive use of template inheritance. You can read more about that in the Django documentation, or in this nice article. The inheritance feature lets use replaceable, named blocks.
  • The OpenHatch code is broken up into different Django apps. The LAYOUT file explains these apps a little bit.

Who should read this?

You should read this if you are:

  • Writing a new page, and want to get a sense of how things work together
  • Curious to learn how we use Django templates

Begin at the begin: base.html

All web pages that render into HTML eventually extend from base.html. You can look at the current version in Github, on the web.

Important template blocks in the <head> of the document

  • title: If you want your page to have a custom HTML TITLE, override the title block. It gets wrapped inside the whole_title block.
  • js_in_head: You can override this if your page needs to add JavaScript tags to the <head> section of the HTML document. Use sparingly, as putting JavaScript here will cause the browser to wait for the script to load before rendering the document.
  • css: If you want to add custom CSS, you can add it by extending this block. Be sure to invoke 
    {{ block.super }}
    at the top if you do that, or else you'll accidentally erase a bunch of main site CSS.

Generally useful template blocks for the <body>

The most useful one:

  • content: This is where the main page content goes. Probably, you're not going to be using base.html directly; you'll be inheriting from some page that inherits from it. That page will probably wrap your content in some more fluff.

The rest:

  • body_id and body_class: If you want your page to provide a hint to CSS as to what page it is, you can use these.
  • nav: This adds the top navigation links.
  • 'greeting: Some view functions set the "explain_to_anonymous_users" flag.
    • Note: In my opinion, the greeting block should be extracted out, like 'greeting.
  • pagetop: Stuff included toward the end of the navigation bar.
  • footer: You probably don't want to override this.
  • js_before_bundle and js: If you want to add JavaScript to the page, you can put it here. You should use js unless you know you have a reason not to.
    • Note: If you're using this, you should probably talk to us on IRC or the mailing list about adding your JavaScript file to the bundle.

A tour of a complex template: landing.html

This page:

  • extends base.html.

It overrides:

It uses:

  • The cache template tag, so that lots of people loading this popular page doesn't cause us to do a lot of computation.

And then it mostly uses modules lay itself out. A module in the OpenHatch CSS is just a box, often with a header.

Retrieved from "https://wiki.openhatch.org/wiki/A_tour_of_the_templates?oldid=5314"