The General Context

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.