Newscoop 3 Cookbook

Organising template files

Every template package available for download from Sourcefabric has three main templates:

  • Front page
  • Section page
  • Article page
These are called - no surprise here - front.tpl, section.tpl and article.tpl.

You could run a publication with these three templates and nothing else. But to make the most of the template engine's power, you should divide up your templates further, creating sub-templates which can be easily reused and edited.

There are some parts of pages which are identical, regardless of the section or the article. This is usually the case for the header, navigation and footer, for example. But it could also be an image stream from flickr, a Twitter feed, a 'Like' button from Facebook, or a similar icon for sharing content from a third party provider.

You don't have to duplicate this part of the template. In fact, it's even better to hand off these functions to sub-templates. Then when you apply a change to the sub-template, it will show up across your entire site.

You can take out sub-templates, place them in a subfolder and call them with an include, like this:

{{ include file="set_thejournal/_tpl/article-comments.tpl" }}

As you can see in this example, the path to the template which is being included needs to be named. Planning your templates' folder structure carefully will save you time later, especially when you run more than one publication on Newscoop and have several different designs in action.

We encourage you to follow the folder structure described below. It's not set in stone; you can structure your templates and folders however you prefer, but the Newscoop community has agreed on this structure after years of working with templates. We consider it to be best practice. Also, the template packs Sourcefabric provides all feature this structure. If you use the same logic it will be easier to use examples or copy sub-templates from one template package to another. Read on to find out what we recommend when it comes to naming templates and placing them in your file system.

Template naming

Besides the main templates (front.tpl, section.tpl, article.tpl) you will probably have many sub-templates to run your publication. Depending on whether they're common across multiple pages, or unique to a page, you may follow these rules. But you don't have to, because Newscoop doesn't have reserved names for specific templates; it's really up to you to create your environment the way you like.

  1. _html-head.tpl is the template we provide for all links, meta tags and information globally needed for your publication, like jQuery, webfonts, CSS files and universal JavaScript.
  2. Unique code for sections or articles can be called from _html-head.tpl using {{ if $gimme->template->name == "path/to/article.tpl" }} or with other IF conditions like switches, topics or keywords. Such additional includes could be slideshows or special CSS files. For quick development, having one template (for example _html-head.tpl) saves you lot of time when you have to introduce some changes, and keeps things consistent. You can always chop it up later.
  3. Includes that are used on more/all pages can have short names, like header.tpl, main-nav.tpl, footer.tpl
  4. Included templates that are specific for a single page (or a few pages from the same context) can have a prefix, like article-sidebar.tpl or front-top-story.tpl. This way you will have templates for article page grouped together in the template file listing. The same goes for archive, front page, search and so on.
  5. Special templates that are not directly used to output content on the web page but to define context (for example the _html-head.tpl which defines the HEAD section of web pages, or some RSS or sitemap generators) can have the '_' (underscore) sign as the first character; this way, all such templates are grouped together on the top of the template listing page.

Folder structure

Your templates will always be inside the filesystem path:

/path/to/documentroot/templates/

These files are accessible through the template editor of the Newscoop administration interface. Inside this folder you can add sub-folders. We recommend the following structure:

Here's some practical advice on how to make your life easier with a clean and functional folder structure:

  1. templates/set_name/
    Replace "name" with the name of your template package. For example, we are using "set_thejournal" for the template package "The Journal". The main templates are placed inside this folder, like front.tpl, section.tpl, article.tpl or universally used templates like search.tpl, archive.tpl, gallery.tpl etc. The include path is:
    {{ include file="set_thejournal/gallery.tpl" }}
  2. templates/set_name/_tpl/
    All your sub-templates are collected inside this sub-folder. In our experience it isn't necessary to divide this into further sub-folders. Instead you should use the name of sub-templates for further clustering, like article-comments.tpl, article-author.tpl, etc. The include path is:
    {{ include file="set_thejournal/_tpl/article-comments.tpl" }}
  3. templates/set_name/_img/
    If you need images on the file system for your publication, place them here. The source path is:
    <img src="http://{{ $gimme->publication->site }}/templates/set_name/_img/logo.png" />
  4. templates/set_name/_js/
    Place all the JavaScript files you need in this folder. They are included like this in the header:
    <script type="text/javascript" src="http://{{ $gimme->publication->site }}/templates/set_thejournal/_js/tabs.js"></script>
  5. templates/set_name/_css/
    You can place universal CSS files into this folder, things like grid, or font sizes. Alternatively you can use a subfolder (see next point). These CSS files are included like this:
    <link href="http://{{ $gimme->publication->site }}/templates/set_thejournal/_css/default.css" rel="stylesheet" type="text/css" />
  6. templates/set_name/_css/skinname/
    For the CSS files, we decided to introduce a subfolder, which is best being described as a skin. For example, the CSS in this folder could change the colour of your site, in which case you might have folders like "red", "blue" and "morning mist" in here. You call these files with:
    <link href="http://{{ $gimme->publication->site }}/templates/set_thejournal/_css/green/green-skin.css" rel="stylesheet" type="text/css" />
  7. templates/set_name/_misc/
    Use this folder for additional code, like a Flash Player which is being embedded in your templates. The URL path is:
    http://{{ $gimme->publication->site }}/templates/set_thejournal/_misc/
    If you need the folder path it would be:
    /path_to_document_root/templates/set_thejournal/_misc/

If you check out our template packages you will see that beyond this strict structure, we actually get a bit looser and let our hair down. For example, you'll find image folders inside the CSS folders, providing background images. A good rule of thumb would be keep your ship in order for as long as you can. Then get flexible and sail with the wind.