Templates

Template Structure

We recommend you follow these guidelines to ensure your templates directory structure remains manageable. More advanced users are welcome to come up with their own structure but our recommended structure is a very good starting point.

Overview

The basic templates are in the root of the template directory e.g. template). These templates should use an appropriate language for the default language for the site.

We should have the following basic templates for all sites.

• base.html
  This is the root template for all pages, that includes the site javascript and CSS. It should expose the following twig blocks:
  • page_title
    a block to allow setting the page title in the head element.
  • page_css
    a block to allow over-riding the CSS for a page.
  • page_js_link
    a block to allow over-riding the Javascript script elements that pull the build JS files into the page.
  • page_body
    a block to allow setting the whole of the body element.
  • page_js_inline
    a block to allow setting page specific inline javascript. These blocks can be over-ridden in each page of the site, if need be.
• site_javascript.html
  this defines inline Javascript that 'bootstraps' each page on the site. It should include the hf_dataLayer setup.
• 404.html
  the template for a page to be displayed when the route is not found.
• standard_layout.html
  this template should extend base.html. It's purpose it to allow setting standard page elements, such as header and footer to be reused by other templates. It should expose the following twig block: page_content

Sites can add other templates that define alternative page layouts to standard_layout.html in the root directory. For example, if a site had multiple page about an emergency appeal, having an emergency_appeal_layout.html that defines the basic look and feel of all of the emergency appeal pages would be appropriate.

Directories

Dijon expects to find templates in the following directories:

• template/page
  Dijon looks here for page templates.
• template/component
  Dijon looks here for component of pages templates.
• template/fragment
  The fragment directory is used to hold templates that are by PHP functions to render elements on a page. It is appropriate for these fragments to have extra variables specific to them.

There is a common templates directory in the Dijon core. This allows us to create templates once for use with shared widgets, as the templates in that directory are available to all sites.

Just to note, it is fine to create subdirectories under the component, fragment and page directories, if that helps organise those templates.

Languages

Although we recommend using Dijon's content management features to manage different languages, you can also specify templates based on language. This can be useful, for example, when content does not fit due to different sized words.

For each language supported by the site, other than the default language, there can be a corresponding language directory under the template directory, e.g. template/fr. Dijon will prefer to use language specific templates when appropriate (i.e. when the user has a language preference).

You can add a language specific versions of the page directory template/fr/page (where fr is the language) which will be used in preference to the default page templates when appropriate.

Page components are stored in the directory template/component. Language specific versions should go in template/fr/component. Dijon will use the language specific template when displaying content for that language when it is defined.

The fragment directory template/fragment can also be localised to language. Language specific fragements should go in template/fr/fragment where fr is the language code.

Precedence

Dijon decides which template to use by looking for the most specifically appropriate template, and then working back to the more generic templates.

For example if had a user with their language set to be French, and Dijon needed to render the donations activity feed, which is rendered through a template named component/activityFeedDonationInfo.html. Dijon would look for these files in order:

• /template/fr/component/activityFeedDonationInfo.html
• /template/component/activityFeedDonationInfo.html
• /common_templates/component/activityFeedDonationInfo.html