Carrington Framework Overview

This post covers the basic similarities and differences between a Carrington theme and a traditional WordPress theme, and the core functionality of the Carrington CMS theme framework. Please read the Q&A first before reading this overview.

Themes created with the Carrington framework work much in the way a traditional WordPress theme does, the difference is in how the code is abstracted and what can be done with those abstractions. The initial response when seeing more files and folders in a Carrington theme seems to be “wow, this is complicated”, but the general process is no different than a traditional WordPress theme.

Here is a diagram that shows the difference between the page load for a single post view in the WordPress Default theme and how the same in done in Carrington:

In this diagram, the items in bubbles are pulled in as included files and the items without bubbles are hardcoded into a parent file.

As you can see, the same things are loaded in the same order. If you dig in and look at the code, you’ll see that the same WordPress template functions are used in both. The difference is in how the template files are structured.

The WordPress Default theme basically follows this code path:

• Load single.php
• single.php includes header.php
• “the loop” is hardcoded into single.php
• “the content” is hardcoded into “the loop” portion of single.php
• single.php includes comments.php, which displays the list of comments and the add comment form
• single.php includes sidebar.php
• single.php includes footer.php

You’ll note that code is hardcoded into single.php and comments.php. This prevents you from re-using that code in other places in the theme the way that more atomic templates for these items would.

Now let’s look at the code path for a Carrington theme:

• Load single.php
• single.php asks the Carrington framework to look for appropriate top page templates in the single/ directory and includes the proper template.
• Next we include a header file – the Carrington framework looks for an appropriate header templates in the header/ directory and includes it.
• The next include is a loop from the loop/ directory – again, selected from available templates by the Carrington framework.
• The loop include will then choose either a full content view of the post from the content/ directory or an abbreviated view from the excerpt/ directory. The template is selected by the Carrington framework based on the available templates and the various data attributes of the post.
• The next include is the comments wrapper from the comments/ directory, again chosen as appropriate by the Carrington framework from available template options for the current page.
• The comments wrapper holds the comments loop, which then includes the appropriate comment template for each comment from available templates in the comment/ directory.
• The comment form is brought in from the forms/ directory – having it separate makes it available for re-use in other places as needed.
• The sidebar is selected by the Carrington framework from available sidebar templates in the sidebar/ directory.
• The footer is selected by the Carrington framework from available footer templates in the footer/ directory.

There appear to be more steps in this process, but if you look you’ll see they are the same steps that are in the WordPress Default theme. There are more files and folders because we’ve taken care to better abstract the distinct bits and pieces of the theme into discreet atomic templates; enabling better re-use of them.

Duplicating code is bad. Developers know this, it’s why they create functions, objects, include files, etc. to avoid having to maintain the same code in multiple places. Designers know it too. It’s why they create CSS stylesheets instead of hardcoding CSS into style tags for every element. Carrington is built from the ground up around native support for atomic templates for various WordPress theme components (to encourage and enable code re-use).

In the Carrington Blog theme, we use the atomic post templates to be able to load in posts individually from the archive pages with AJAX – see an example here. This isn’t easily possible with the WordPress Default theme because the template code for the individual post isn’t abstracted into a separate file.

Above in the page load process I talk about the Carrington framework choosing from available templates for each piece of the theme. This smart template selection is the primary job of the Carrington framework. It allows you to create rich, customized themes for complex CMS web sites by simply creating different template files instead of coding conditional logic into your template files.

You create templates for various conditions, and the Carrington framework uses those templates when it runs across one of those conditions.

It’s also important to note that you don’t have to create more than one template for anything. You could start your site with just default templates in each folder, and have the ability to expand with easy customization later.

The templates in the different Carrington directories are chosen based on one of three supported contexts:

1. General Context – what type of page is this (category page, single page, home page, etc.)?
2. Post Context – what type of post is this (does it have this category, author, tag, custom field, etc.)?
3. Comment Context – what type of comment is this and who left it (comment, pingback, is the user registered, an author, etc.)?

Note: these contexts can be extended and additional data conditions to check can be added using the hooks and filters in the core Carrington framework.

For example, when choosing the template file to use for the header, the process looks something like this:

1. Check for available template files in the header/ directory.
2. Run through conditions from most restrictive to most liberal (the order and conditions are customizable via filter) until a match is found with a template option. When a match is found, use that template.
3. Use the default template if there is no match found to a condition, or no other templates are present.

Each folder in the Carrington themes we provide (including Carrington JAM, our “starting point” theme) includes a README file that explains the purpose of the files in that folder, what context is supported for that folder, and what template naming conventions are supported in that folder by the Carrington framework.

Hopefully this overview has given you a good base from which to understand the core principles in place in Carrington, and how it is similar and different from traditional WordPress theming. In our next installment, we’ll look at the General Context and how to use it.