home > support > web design > wordpress plugin > theme development

WordPress theme development

If you are an experienced WordPress theme designer / developer you can probably skip this page, you may find the links in the "WP Plugin reference" section of the menu to the right more useful.

The basics

Template Hierarchy

Any existing WordPress theme will be - at least partially - compatable with the TourCMS WordPress Plugin, this is due to an inherent feature of WordPress called Template hierarchy. Template hierarchy means that WordPress will use as specific a template file as it can find for a particular page, the Template hierarchy diagram shows the full extent of this.

For example when viewing a Tour/Hotel we would like WordPress to use a special template so that the page appears differently to blog posts or regular pages; perhaps hiding the ability to comment, or adding a standard area for price & duration information. The important section of the hierarchy diagram for this is as follows:

single-posttype.php --> single.php --> index.php

Specifically, as we are building a page for Tour/Hotel type posts the hierarchy will be:

single-tour.php --> single.php --> index.php

So, we probably want to create a template named single-tour.php for displaying our Tours/Hotels, otherwise WordPress will default to single.php (if it exists) or index.php.

We would also want to display lists of Tours/Hotels differently to lists of blog posts or other pages, the important section of the hierarchy diagram for this is as follows:

taxonomy-taxonomy.php --> taxonomy.php --> archive.php --> index.php

There are two custom taxonomies incuded with the TourCMS WordPress Plugin, so the following hierarchy will be used when listing products by "Product type" (e.g. "Hiking tours" or "All tours"):

taxonomy-product-type.php --> taxonomy.php --> archive.php --> index.php

And the following when listing products by "Location" (e.g. "All tours in Scotland" or "All tours in the UK"):

taxonomy-location.php --> taxonomy.php --> archive.php --> index.php

If you are planning to use an exisiting WordPress theme, then unless a theme has been specifically developed for TourCMS then these templates will not exist. However, all is not lost and we can use another feature of WordPress called Child themes to build them.

Child Themes

A WordPress child theme is a theme that inherits the functionality of another theme, called the parent theme, and allows you to modify, or add to, the functionality of that parent theme.

So if we have an existing (non TourCMS Plugin optomised) WordPress Theme we can build a new child theme for it containing just the TourCMS Plugin specific templates and CSS changes, leaving the existing theme intact.

Step by step example

WordPress 3.0 introduced a great default theme called Twenty Ten. Twenty Ten is a nice and simple theme that is easy to build on, so we will build a child theme on top of that for this tutorial. If you have an another theme you wish to develop on top of the process is the same.

Basic setup for a child theme

A child theme resides in its own directory in wp-content/themes. The scheme below shows the location of a child theme along with its parent theme (Twenty Ten) in a typical WordPress directory structure:

  • public_html
    • wp-content
      • themes (directory where all themes are)
        • twentyten (directory of our example parent theme, Twenty Ten)
        • tourcms-twentyten (directory of our child theme; can be named anything)
          • style.css (required file in a child theme; must be named style.css)

This directory can contain as little as a style.css file, and as much as any full-fledged WordPress theme contains. Here's an example style.css:

/*
Theme Name: TourCMS Twenty Ten
Description: Child theme for the Twenty Ten theme 
Author: Your name here
Template: twentyten
*/

@import url("../twentyten/style.css");

#site-title a {
    color: #009900;
}

What the above code does is give our child theme a name (TourCMS Twenty Ten), a description, defines which parent theme to use (twentyten), imports the parent themes stylesheet and then sets a new link colour.

If you save this as style.css in your child theme folder you can then go into WordPress admin and choose your new child theme, you should see the links on your WordPress site change colour (you can remove the three lines for that, it's just a nice simple way to test that we have a working child theme). Any custom CSS required in the child theme can be added to style.css.

We can now progress to building our template files.

Deciding which template files to create

Template file for displaying individual Tours/Hotels

Lets take another look at the template hierarchy for the Tour/Hotel single page:

single-tour.php --> single.php --> index.php

Our parent theme "Twenty Ten" already has an index.php and a single.php, what we will do is build a single-tour.php in our child theme and WordPress will automatically use that for our Tour/Hotel pages. What we need to do is:

  1. Take a copy of single.php from the twentyten theme directory and place it into our tourcms-twentyten directory
  2. Rename our copy to single-tour.php

Template file(s) for displaying lists of Tours/Hotels

Lets take another look at the hierarchy for pages with lists of Tours/Hotels:

taxonomy-taxonomy.php --> taxonomy.php --> archive.php --> index.php

Our parent theme "Twenty Ten" already has an index.php and an archive.php, what we will do is build a taxonomy.php in our child theme and WordPress will automatically use that for our Tour/Hotel listing pages (If we wanted to could instead create separate taxonomy-product-types.php and taxonomy-location.php templates). What we need to do is:

  1. Take a copy of archive.php from the twentyten theme directory and place it into our tourcms-twentyten directory
  2. Rename our copy to taxonomy.php

When you are done your theme directory should look like this:

  • public_html
    • wp-content
      • themes
        • twentyten
        • tourcms-twentyten
          • single-tour.php
          • style.css
          • taxonomy.php

Editing single-tour.php

As we have taken a copy of single.php what we are starting with is a generic template for displaying any post-type that doesn't have it's own template; so there is a fair amount of code to delete / comment out. For example the chunk of code that begins <div id="nav-above" class="navigation"> (starts around line 17 for three lines) is displaying a list to the previous post, this is unlikely to be required when viewing a Tour/Hotel and can be commented out and then deleted.

Remember this template will only be used by WordPress for displaying an individual Tour/Hotel, the original copy of single.php will still be used for existing post types.

Finally we can add in the code to display the custom Tour/Hotel information that the plugin pulls down from TourCMS, such as prices, availability, product type, location information, special notices etc. This information is made available via the post "Meta" and can be retrieved using the get_post_meta function, for example the following code will display the Duration description as loaded in TourCMS (e.g. "7 nights" or "Half day"):

<?php echo get_post_meta( $post->ID, 'tourcms_wp_duration_desc', true ); ?>

The full list of available Meta data can be found on the Meta data & shortcodes page. For some common tasks such as embedding a booking engine Template hooks are available, for example the following code will add a booking engine to the page:

<?php tourcms_wp_book(); ?>

The link text (if applicable) and behaviour (link, popup window, iframe) of the booking engine can then be controlled in the Plugin settings, accessible via the WordPress admin pages. The booking engine links are also available as Meta data, however you may find using the hook saves time, view more template hooks.

Editing taxonomy.php

Following a proccess similar to editing single-tour.php go through removing the parts that you don't want to be displayed (things like post dates, authors etc) and adding in desired information like thumbnail images, "from" prices or accommodation grades; again using the Meta data & shortcodes page as a reference.

If you get stuck please do contact us.

Download the theme

A download link for the completed example child theme is available on the installation page.

<body>