Newscoop 4 Cookbook

Creating a Newscoop theme

A set of templates designed for Newscoop can be used to create a Newscoop 4 theme in a single zip file by following some simple formatting rules...

1. A theme.xml file needs to be created before the new theme will show up in the Configure -> Themes page of the administration interface. This file contains a name, designer's name, version and description for the theme, and references the default templates and renditions for the theme.

The name= value has to be unique for each new theme that you create. If you have based a customised theme on one of the themes distributed with Newscoop, be sure to change the name before you install it. Otherwise, your customised theme may be overwritten when Newscoop is upgraded.

The require= value specifies the minimum version of Newscoop that the theme was created for. The theme.xml file should also reference some preview screenshots with the <presentation-img> tag, to help journalists identify the theme in the Newscoop administration interface.

An example theme.xml file could look like this:

<?xml version="1.0"?>   
<theme name="Mytheme" designer="me" version="1.0" require="4.0">
<description>My theme</description>

<presentation-img src="preview-front.jpg" name="Front page"/>
<presentation-img src="preview-section.jpg" name="Section page"/>
<presentation-img src="preview-article.jpg" name="Article"/>

<!-- =============================== -->

<output name="Web">
<frontPage src="front.tpl"/>
<sectionPage src="section.tpl"/>
<articlePage src="article.tpl"/>
<errorPage src="404.tpl"/>
</output>

<renditions>
<rendition name="topfront" width="500" height="333" specs="crop"/>
<rendition name="thumb" width="150" height="100" specs="crop"/>
<rendition name="sectionthumb" width="250" height="167" specs="crop"/>
<rendition name="articlebig" width="600" height="450" specs="crop"/>
<rendition name="square" width="150" height="150" specs="crop"/>
</renditions>

</theme>

2. The theme files should be in the root directory of the zip file (not a sub-directory, such as the name of the theme). Sub-directories are allowed for includes such as _tpl and _css, but the four master templates, assigned to the front, section, article and 404 pages, must be in the zip file root.

3. Include paths no longer reference the name of the theme in Newscoop 4.0 onwards. All paths are relative to the zip file root. For example, you now include a sub-template like this:

{{ include file="_tpl/_html-head.tpl" }} 

instead of the way it was done in Newscoop 3:

{{ include file="set_mytheme/_tpl/_html-head.tpl" }}

4. To avoid hard-coding theme names into link paths, you can use the url static_file function:

<link href="{{ url static_file='_css/general.css' }}" media="screen" rel="stylesheet" type="text/css" /> 

instead of using the full link path, which is inflexible if the name of your theme is changed at some point in the future:

<link href="http://{{ $gimme->publication->site }}/templates/set_mytheme/_css/general.css" media="screen" rel="stylesheet" type="text/css" /> 

Taking a look at the source of the rendered page, the url static_file function should create a link something like this:

<link href="http://www.example.com/themes/publication_2/theme_5/_css/general.css" media="screen" rel="stylesheet" type="text/css" />

Newscoop figures out which publication alias, publication number and theme number you wanted, and constructs the link from that information. This means you can rename themes, fork themes or move them around, and not break links.