This describes the Comment Context, a concept in the Carrington CMS theme framework for WordPress. Before reading this, you should read the Q&A and the Framework Overview.

In this article we will review some real world examples and cover how the Comment Context works and where it is used. The Comment Context allows you to customize how comments are shown based on information about the comment and the person who left the comment.

Scenario #1 – Registered Users

On a site that wants to encourage our visitors to register, giving registered users enhanced comment displays is a nice approach to take. Perhaps the standard comment display shows just the commentor’s name, but a comment by a registered user shows their name, a link to their web site, a photo, etc.

Accomplishing this with Carrington is very simple. You don’t have to write any conditional PHP code, you can simply create a new comment template and Carrington will do the rest.

Assuming registered users have a role of “Subscriber”, we create a template file named role-subscriber.php and place it in the comment/ folder. In that template file you include the HTML for the links, etc. that you want to display for your registered users. Carrington will use that file for comments by registered users.

Scenario #2 – Pingbacks

You may want to have custom displays for pingback and trackback comments to differentiate them from other comments. Perhaps you want to display a small screenshot of the page that has sent the pingback to your post.

Doing this custom display is easy with Carrington. Simply create a ping.php file in the comment/ directory, and place the HTML and associated code for the web site thumbnail into that template. When displaying a comment that is a pingback or a trackback, Carrington will use this template file – showing your site thumbnail as well.

No need to inline conditional PHP code in your template, just create templates for the conditions you care about and the Carrington engine will take care of the rest.

Scenario #3 – Celebrities

If you are running a site in which certain individuals are very important, you may want to take advantage of the Carrington feature which allows you to create custom comment templates on a per-user basis.

If you are running a U2 fan site and Bono drops by to leave a comment, you probably want to highlight that comment. To do this, simply create a user-bono.php template (where “bono” is the username) in the comment/ folder and that template will be used for comments by Bono.

This feature can also be useful to distinguish real comments by a particular user from comments by someone else with (or using) the same name.

As you can see, Carrington makes it really easy to create custom comment displays for different situations without writing any conditional PHP code.

Comment Context Documentation

When choosing a template to use in the Comment Context, the Carrington engine looks at the type of comment and the author of the comment to choose which template to use.

A “default” template is required, and will be used when there are no other templates that match a given comment. This could be because no other templates have been created, or because the comment in question doesn’t match the templates that are available.

The order in which these conditions are checked defaults to the following:

1. ping
2. author
3. user
4. role
5. default

however this order can be overridden with a plugin using the `cfct_comment_match_order` hook.

Once a template match has been found, no other processing is done.

Supported Templates (Comment Context)

• comment-default.php – Used when there are no other templates that match for a given comment.
• ping.php – Used if the comment is a pingback or a trackback.
• author.php – Used when the author of the post leaves a comment.
• user-{username}.php – Used when a user with that username leaves a comment. For example, a template with a file name of user-jsmith.php would be used for a comment by user jsmith. Any WordPress username can take the place of {username} in the file name.
• role-{role}.php – Used when a comment is made by a user with a certain role. For example, a template with a file name of role-subscriber.php would be used for a user with a role of “subscriber” (typical for a registered commentor who is not an author or an admin). Any WordPress role can take the place of {role} in the file name.

Create templates with names using these patterns and place them into the directories (comment) that use the Comment Context. The templates will be used when a situation arises matching their named condition.

This has been an overview of the Comment Context of the Carrington CMS theme framework for WordPress. You may want to look at the General Context and Post Context next.

Community additions to the documentation and resources for Carrington (including this page) are very welcome.

This describes the General Context, a concept in the Carrington CMS theme framework for WordPress. Before reading this, you should read the Q&A and the Framework Overview.

In this article we will review some real world examples and cover how the General Context works and where it is used. The General Context allows you to customize how general parts of your theme (header, footer, sidebar, etc.) are shown based on information about the type of page being shown.

Scenario #1 – Custom Sidebar

You’re building a personal web site/blog. One of your categories is “Photos”, a place where you post some of your photos and perhaps some of your thoughts on photography. For this section, you want to add a little something extra to your sidebar – you want to include your most recent photo, a Flickr slideshow, etc. at the top of the sidebar.

Using Carrington, this is very simple. You create a new file in your sidebar/ folder called cat-photos.php and Carrington will use this sidebar when showing the category archives for the Photos category.

If you want also use a custom sidebar template for any single post in this category, you can create another template in the sidebar/ directory called single-cat-photos.php. This template will be used for single post views when the post is in the Photos category.

Bingo, you’ve got a custom sidebar that is only used when you want it.

Now you may be thinking “Wait a minute, what about code duplication? I thought that was bad…” – you’re right. However multiple templates doesn’t necessarily mean code duplication. Remember this is all just PHP, you can put your common code in a file called common.php or similar and include that in each sidebar file. Perhaps that file is showing a dynamic sidebar if you’re using dynamic sidebars and widgets. In the scenario above, you might simply include the cat-photos.php file in the single-cat-photos.php file.

Can you do this with conditional code in a single template? Sure. What Carrington gives you two-fold: is a consistent way to manage all of these conditions using simple named templates and the ability to make this change without writing any PHP code (designer friendly!). Also, this is just very a simple example, the more complex the site you are building, the more Carrington will help you out.

Scenario #2 – Custom Headers

You’re building a magazine web site that uses custom header graphics and elements for different categories and author archives. The headers include custom elements like live scores in the Sports category, weather conditions in the Weather category, and a headshot and mini-bio for the author archives.

In this example, you can see how the conditional code in header.php would start to get fairly complex in a traditional WordPress theme.

The files you would create in this scenario are: cat-sports.php, cat-weather.php, author-jsmith.php, authorsjones.php, etc.

In each file put in the HTML, PHP function calls, etc. for the content you need for that category or author archive. Remember, you can include common code into each of these templates from a separate common template if necessary.

General Context Documentation

The Carrington framework enables customizability based on matching contexts and file templates that conform to the Carrington template naming conventions.

The General Context refers to type of page that is being shown. This context is used when selecting a template from the following directories:

• attachment
• comments
• footer
• header
• loop
• posts
• sidebar
• single

When choosing a template to use in the General Context, the Carrington engine looks at the type of request is being fulfilled. It will identify the request as the home page, a category archive, and individual post, etc.

There is additional checking done for single post requests. All options in the Content Context are supported here with a ‘single-’ prefix added to the file. See specifics below.

A “default” template is required, and will be used when there are no other templates that match a given comment. This could be because no other templates have been created, or because the comment in question doesn’t match the templates that are available.

By default, conditions are checked in this order:

1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)

This order can be altered (and added to) using the `cfct_general_match_order` filter.

Supported Templates (General Context)

• {dirname}-default.php (or default.php) – Used when there are no other templates that match for a given page/post.
• archive.php – Used for date archives or if there are no specific category, author or tag templates.
• author.php – Used for author archive lists.
• author-{username}.php – Used when the post/page is authored by a specific user. For example, a template with a file name of author-jsmith.php would be used for a post/page by user jsmith. Any WordPress username can take the place of {username} in the file name.
• role-{rolename}.php – Used when the post author has a particular role. This might be the role of contributor, author, editor, etc. and use a file of role-contributor.php, role_author.php, etc. where the role name takes the place of the {rolename} in the file name.
• category.php – Used for category archive lists.
• cat-{slug}.php – Used fr displaying a given category. The category is matched by the “slug” – for example a post in category “General” (with a category slug of “general”) could use a template of cat-general.php.
• home.php – Used when on the home page.
• page.php – Used for pages that do not match any other contextual templates.
• search.php – Used when displaying search results.
• single.php – Used for single post pages.
• single-{content context filenames}.php – Used for single post pages.
• tag.php – Used for tag archive lists.
• tag-{slug}.php – Used for displaying a given tag. The tag is matched by the “slug” – for example a post in tag “News” (with a tag slug of “news”) could use a template of tag-news.php.

Create templates with names using these patterns and place them into the directories that use the General Context. The templates will be used when a situation arises matching their named condition.

This has been an overview of the General Context of the Carrington CMS theme framework for WordPress. You may want to look at the Post Context and Comment Context next.

Community additions to the documentation and resources for Carrington (including this page) are very welcome.

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.

Alister Cameron has a nice video talking about what he sees as the win with the Carrington CMS theme framework.

He obviously “gets it” – we need to do a better job evangelizing and providing examples. We’re working on it – would love to have community contributions around this as well.