Canvas Template System

In Canvas, the WordPress theme template system has been taken one step further, to provide a better separation between the design (HTML) and the logic (PHP and WordPress template tags). This allows for more granular control over your theme. For example, it’s possible to customize how a specific post type, or even a specific entry, is displayed within search results and archive screens. It also means that it’s possible to make modifications to one section (for example, the design) without needing to dive into the WordPress Loop. The Canvas templating engine has three levels:

Traditional WordPress templating structure (index.php, archive.php, single.php, etc.),
Loop structure (loop.php, loop-blog.php, etc.), and
Content structure (content-post.php, content.php, etc). In the system, these load as follows:

Index.php example

↑ Back to top

Take, for example, the index.php template, which is commonly used as the homepage (posts page) template at Woo.

<!-- #main Starts -->
<?php woo_main_before(); ?>
<section id="main" class="col-left">
 
<?php
  if ( is_home() && is_active_sidebar( 'homepage' ) ) {
    dynamic_sidebar( 'homepage' );
  } else {
    get_template_part( 'loop', 'index' );
  }
?>
 
</section><!-- /#main -->
<?php woo_main_after(); ?>

When this file loads, Canvas does the following:

Take the design from the index.php page and display it.
Inside index.php, look for a file called loop-index.php (with a fallback of loop.php) and load it.
Inside loop-index.php, for each post/page we’re displaying, search for it’s appropriate content-XXXX.php file (with a fallback of content.php).

Each of these pieces is context aware (for example, searching for loop-index.php on the index.php template, or loop-archive.php on the archive.php template). This makes it possible to make customizations to very specific areas of your website (for example, the loop structure on all archive screens, or just the loop structure on your homepage).

<?php
  while (have_posts()) { the_post(); $count++;
    woo_get_template_part( 'content', get_post_type() );
  } // End WHILE Loop
  } else {
    get_template_part( 'content', 'noposts' );
  } // End IF Statement
  woo_loop_after();
  woo_pagenav();
?>

Example

↑ Back to top

An example of the loop.php file and how we use the woo_get_template_part() function to load the content templates. The default TwentyTen theme makes use of the traditional template structure, as well as the loop files concept. The newest feature here is the content templating structure. This is what provides the granular control of your website at a per-post level. Looking at a single post as an example (with an ID of 1173 and a slug of “test-of-image-attach-2″, Canvas will be told to look for the most appropriate content template out of the following list:

content-archive-test-of-image-attach-2.php (archives and posts page only)
content-archive-post-1173.php (archives and posts page only)
content-single-test-of-image-attach-2.php (single posts/pages only)
content-single-post-1173.php (single posts/pages only)
content-test-of-image-attach-2.php
content-post-1173.php
content-archive-post.php (archives and posts page only)
content-archive.php (archives and posts page only)
content-single-post.php (single posts/pages only)
content-single.php (single posts/pages only)
content-format-aside.php
content-tumblog.php
content-post.php
content.php

This breaks down to mean the following:

content-archive-slug.php (archives and posts page only)
content-archive-posttype-ID.php (archives and posts page only)
content-single-slug.php (single posts/pages only)
content-single-posttype-ID.php (single posts/pages only)
content-slug.php
content-post-ID.php
content-archive-post.php (archives and posts page only)
content-archive.php (archives and posts page only)
content-single-post.php (single posts/pages only)
content-single.php (single posts/pages only)
content-format-postformat.php
content-tumblog.php
content-posttype.php
content.php

What the system being told to do here is as follows:

“Canvas, here’s a list of possible templates that apply to this post. When you find the most appropriate match, use it and stop looking.”

Based on the above information, we know that, if we load a file into our child theme called content-archive-test-of-image-attach-2.php, we can customize how that post will be displayed within all archive screens (category, tag, posts page, etc), without any unnecessary conditions inside a loop that could overcomplicate and confuse what we’re trying to achieve. It also means we don’t have to duplicate code in our child theme which isn’t relevant to the customization we want to make. Another example of a way to use this content templating structure would be when a product catalog has been loaded. In our imaginary product catalog, the custom post type used to create the products is a post type called product. We may want to display relevant information here, such as a price, featured image and product rating. By creating a content-archive-product.php file in our child theme, we can customize how only the products are displayed, without needing to modify any loops or dive into too much code. As seen in the second list above, this content templating engine comes bundled with support for both WooTumblog and it’s use of post formats, ready to customize to suit your every need. We hope this clarifies the Canvas templating engine, it’s levels and how you can maximize Canvas with even more control over your templates.

Canvas Template System

Requirements

Template structure

Index.php example

Example