Porting a Template into a PostNuke Theme

Important Note: This tutorial generates a theme for PostNuke 0.8x

Introduction

In this tutorial we'll take a web template and convert it into a PostNuke Theme. The web sites Open Source Web Design∞ and Open Web Design∞ contain many quality templates all of which are open source. The majority of these templates are of a higher quality, at least in terms of markup quality, than many commercial templates - what's more the price is right!

Not all templates are packaged the same but this tutorial should serve as a good outline of the general procedures required to take a static template into the PostNuke environment. For the purposes of this tutorial we'll use the excellent 1024px∞ template by Andreas Viklund∞ - author of the andreas08 template currently shipped with the PostNuke 0.8 milestone releases.

Getting Started

Now that the background has been covered lets get started. Firstly download the template from oswd.org and extract the archive. Once extracted you'll have a directory called 1024px containing two templates (index.html and index-alt.html), a stylesheet (style.css) and an images directory. The file index-alt.html is an alternative layout for the template which we'll put to one side and concentrate on the standard layout. For the purposes of this tutorial delete the file index-alt.html.

During the tutorial this directory will be referred to as the 'template root directory'.

Restructuring the Template

We're now left with one template, one stylesheet and some images. Lets begin to change the structure into that required by PostNuke. Create a directory call style below the template root and move style.css into this folder. Moving the stylesheet will have broken any references to images in the stylesheet so we'll need to correct these. Open the stylesheet in your favorite TextEditor and perform a search and replace url(images/ for url(../images/. This will correct the paths to locate our templates images. In this case there was only one match but other templates vary in thier use of images.

Next create the directory 'templates' in the template root. Rename index.html to master.htm and move it to the templates directory. At this point we've re-arranged the files supplied with the template into a form suitable for creating a PostNuke theme.

Creating the Theme Version Files

In order for PostNuke to detect a theme there must be a theme version file (version.php) in the template root and its assoicated language file (<template root>/lang/<lang>/version.php). This file contains the information used by PostNuke to identify the theme. Create the file version.php containing the following simple php code.

Edit the author and contact fields to contain suitable information. For this we recommend that, if you intend to distribute the theme, that you include both your own contact details and the original template authors details. Place your contact details first to indicate the primary contact point for the PostNuke theme version of the template. Seperate multiple contacts with commas e.g.

Next create the language file for the new theme. Firstly create the directory structure required for the language file <template root>/lang/<lang> e.g. <template root>/lang/eng. Create the file <template root>/lang/<lang>/version.php e.g. <template root>/lang/eng/version.php containing the following simple php code. Adjust the text as required.

Important Note: The constants used to define the name, display name and description must be unique so it's recommended that, as with this tutorial, that the theme name is included in the constant name.

Creating the Theme Configuration Files

Theme configuration files tell PostNuke which theme template to use. When performing the initial port of a static template we need to create some initial configuration files so that PostNuke can locate our ported template. Create the directory <template root>/templates/config. This directory holds our theme configuration files. In this directory create four text files with the following names and initial content.

pageconfigurations.ini

This file defines what page configurations are available. In this case there will be just the one page configuration which will apply to all pages.

master.ini

This file defines what theme templates will be used to render each part of the output generated by PostNuke. This page configuration uses the template master.htm for the page and block.htm for each block. There are no specific templates defined for block types or block instances. Additional the palette named 'palette1' will be define the colours available to PostNuke blocks and modules.

themevariables.ini

This file defines any theme variables that will be available to any theme templates. In this case there are no theme variables.

themepalettes.ini

The file defines what palettes are to be used by PostNuke blocks and modules. A palette is used, for example, when creating inline styles. The palette will, later, need to be matched to the colours used in the template and its stylesheets.

Applying the Standard Header

The next step in converting our template is to add a standard header that will pull in the the stylesheet from its new location as well as define the page language, character set, title and keywords. Edit <template root/templates/master.htm and replace the opening html tag and the entire header (i.e. <head> to </head>) as follows

becomes

Important note: in the code above you have to replace ''('' and '')'' with ''<'' and ''>'' due to SafeHTML restriction

Importing the Theme into PostNuke

We now have the basics required for a PostNuke theme so it's time to test what we have in the PostNuke environment. Copy the template root directory (1024px) directly into the themes directory of your local test PostNuke installation. Login to your PostNuke installation and go to the themes admin panel. Regenerate the themes list to detect your new theme. At this point DO NOT SET THIS THEME TO YOUR DEFAULT THEME since the theme templates do not contain the tags to locate the dynamic content created by PostNuke. All you have at this stage is a theme version of a static template containing just the static output.

Preview the template conversion so far by clicking on the theme name. The theme should now look just like the original template. Note that the centre image is expected to be broken due to an incorrect path which will be corrected later.

Note: Missing image here (doku conversion ?) {{templating:1024px-a.png}}

Modifying the Tempate Body

The next step in our conversion is to work through the template adding the dynamic tags required to convert our template into a theme. While the general process is similar for all templates the actual steps taken are very specific to the actual template being converted.

Replacing Basic Template Components

The first step is to replace some of the basic template components with dynamic tags.

Replace the site header

Replace

with

The tag pngetbaseurl generates the URL to the site. The sitename tag generates the sitename set in the base site settings. Note that we've lost a small amount of the template look and feel in this replace. Part of the site name was rendered with a span of class 'fade'. This is not easily achievable when creating a fully dynamic theme although can be done with some suitable custom coding.

Replace the site slogan

Replace

with

The slogan tag generates the site description as defined in the base site settings.

Updating the site footer

Replace

with

The pnmodurl tag creates a link to a module. In this case we've used the modules Forimula, Legal and xSitemap to display our content. Backend.php provides the RSS feed for the news module. The sitename tag has already been covered.

Creating Block Templates

Next we add tags to display our block positions and create the block templates. This template is a two column design so the concept of left and right blocks isn't a natural fit. In order to simplify installation for other users we'll display both left and right blocks in the left column. However first we need to create our block template.

In the page template - master.htm - we see that there is a div with the id 'sidebar'. This contains our left column. Each section of the left column is rendered using

This markup forms our block template. Create the directory <template root>/templates/blocks and then the file <template root>/templates/blocks/block.htm. Edit the file block.htm and add the following content.

The template checks if the block has a title and, if so, renders it inside a h2 tag. The block content is then rendered. Now remove all the content from the div of id 'sidebar' and replace it with

Lastly we'll use the blue box at the bottom of the main column to display our centre blocks. At this point we'll need to create a new block template and alter the templates assigned in the page configuration. Create the file <template root>/templates/block/centre.htm. Edit this file and add the following html

This new block template is the same as the standard block template but wraps the output if a div of class 'box'. Now in the main template replace

with

Finally edit the file <template root>/templates/config/master.ini and change

to

Note: This could also be easily changed from the theme admin panel but since we're working with the file system already and have a TextEditor open this is quicker.

Creating News Templates

While not a required part of a template conversions the news module was a key part of earlier PostNuke releases. Additional this template this useful for a 'news' article based site. The static content remaining in our page template renders two 'news article' type pieces of content; 'As simple as it gets...' and 'Blog/CMS theme versions'. We'll use this markup as the basis for our news templates.

In PostNuke 0.8 themes provide templates for the news module as a standard template override. Firstly create the directory structure for our news templates. Create <template root>/templates/modules and then <template root>/templates/modules/News. Create two empty files in <template root>/templates/modules/News named news_user_index.htm and news_user_article.htm. The first displays the intro text to the news article and the second displays the full article.

Edit the file news_user_index.htm and add the following markup.

Edit the file news_user_article.htm and add the following markup. The two template variables render the category and title information in a h2 tag and the article intro text in a div tag.

The two template variables render the title in a h2 tag and the full article text in a div tag. The following tag displays the article pager should the article have multiple pages. The last two tags are for any display hooks associated with the article.

Displaying the module output

Now we've created the templates for the news module we can remove the markup that generated the static 'news articles' and replace it with the tag for the module output generated by PostNuke.

Replace

with

At this point we have completed replacing all the static content with our dynamic content tags. Previewing our theme looks like

insert image here....

We can see that, at this point, our output doesn't look perfect, especially using a site containing the default PostNuke blocks, but that we now have a basic theme which can be manipulated.

Tidying and Customising the Template and Stylesheets

With most ports of a static html template there will be some tidying up to do. Most templates define css styles for tags that are used to create the initial template but this doesn't take into account all the possible output that a CMS such as PostNuke can produce. Therefore after porting a template there will always be the need to activate the newly created theme on a site for debugging purposes.

h1 style inside main content

With the 1024px theme the first and most apparent issue is that the h1 tags rendered as part of the module output (main content) have the same style applied as the header h1 tag resulting in some very large module headers. To solve this we updated the style applied to all h1 tags to just apply to h1's in the header.

i.e. h1 {....} becomes #header h1 {.....}

We then add another style for remaining h1 tags. In this case something like the following simple style would apply.

Adding standard PostNuke styles and preview images.

The penultimate step is to add any required postnuke styles to the template and to create the two images required by the theme switcher.

Adding standard empty index.html files

The final step is to add empty (0 byte) index.html files to prevent directory browsing of the source files. Create an empty index.html in each directory of the theme.

Summary

This tutorial has covered the steps necessary to port a sample static template into a PostNuke theme. The tutorial covers many of the techniques required for theme building. The result of this tutorial can be downloaded from the mwXanthiaThemes∞ NOC project and previewed at Mark's pnLab Site∞.

---

Theme Authoring Index Page
CategoryDeveloperDocs