The Post Context
This describes the Post 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 Post Context works and where it is used. The Post Context allows you to customize how posts are shown based on information about the post and the post author.
Scenario #1 – Twitter Posts
A common feature in blogs these days is the custom display of a post based on some information about the post, like what category the post is in. Using a plugin like Twitter Tools, you can bring in your tweets from Twitter as blog posts in WordPress.
These posts are different than your other blog posts, and you’d like to style them accordingly. Carrington was built for this.
We’ll assume that the Twitter posts all have a Twitter category attached to them (alternatively you could use tags or post meta instead if you wanted to – Carrington supports these as well). Normally to make these posts look different, you’d add some code into your loop that checks if the post is in the Twitter category, then shows different HTML accordingly. With Carrington, it’s much simpler.
Create a new template named cat-twitter.php in the content/ directory and when a post is displayed that is in the Twitter category, it will use this template instead. You can edit the HTML for this template to remove the title, the category and tag list – maybe add a little Twitter icon or similar to it and a link to your Twitter page.
It’s that easy – you don’t have to know how to write the conditional PHP code to make it happen. With Carrington, this level of customization is comfortably extended to the domain of designers.
Scenario #2 – Columnists
When creating news/magazine sites it’s pretty common to have a “columnist” feature that you need to support. This means that certain authors need to be treated specially. For example, let’s say I’m building a WordPress content site and we have Matt Mullenweg writing a monthly column. We’ll want to give these articles a special treatment so that they stand out visually from the other posts on the site. With Carringon, this is easy.
To create a template that is used for Matt’s pieces, we simply create a user-matt.php file (this assumes Matt’s username is “matt”) in the content/ folder that shows a nice headshot of Matt at the top, and some musical notes (a nod to his love of jazz) sprinkled along the bottom of the post. Now whenever that post is shown, Carrington will find the Matt template and use that instead of the standard template.
If you also want to highlight these posts when showing the post excerpt, that’s just as easy. Create a user-matt.php file in the excerpt/ folder with Matt’s headshot included and it will use that whenever the post excerpt is shown.
Again, Carrington’s power brings you easy customization and flexibility without needing to write any PHP code. The same approach can be used for user groups as well – Carrington supports WordPress roles (editor, contributor, etc.) and named templates for these roles.
Scenario #3 – Google Maps
Attaching additional information to a post is another common need when creating a WordPress as a CMS web site. Carrington makes it easy to use this information to change the display of posts.
On your WordPress powered site you have posts that need to include Google Maps. The Google Map information is stored in a custom field called “gmap” and you want to display the Google Map for these posts.
I think you know what’s coming next. With Carrington you can simply create a meta-gmap.php file in the content/ directory that includes the necessary code to embed your Google Map using the data in your custom field.
Again, no need for conditional PHP code in your theme for this – simply create your template and let Carrington take care of using it for you.
Scenario #4 – Featured Posts
The above example is perfect for situations where you want to do something based on the key of the custom field. Carrington also supports templates based on both the key and value of the custom field.
Another custom field you might want to support is a “featured post” field – perhaps you want to make sure that your featured post template is only used when there is a custom field with a key of “featured” and a value of “yes”. It’s easy with Carrington, you just create a file named meta-featured-yes.php in your content/ directory and Carrington will choose that file for these posts.
I hope this illustrates how Carrington allows you to use custom templates instead of conditional code to customize the way post content is displayed in your theme.
Post Context Documentation
When choosing a template to use in the Post Context, the Carrington engine looks information (author, category, tags, custom fields, etc.) related to the post/page being shown.
Commonly these templates are included by templates in the _loop/_; but are also useful for bringing in an atomic post representation via AJAX or placing one within another template.
A “default” template is required, and will be used when there are no other templates that match a given post. This could be because no other templates have been created, or because the post in question doesn’t match the templates that are available.
You can create templates to be used with posts/pages given various conditions. For example, you might want to give all posts in a certain category some specific styling rules. Or perhaps posts with a certain custom field or by a specific author. This is accomplished by creating templates with file names that match these conditions, then placing them in the _content/_ directory. All templates other than _{dirname}-default.php_ are optional.
The order in which these conditions are checked defaults to the following:
- author
- meta
- category
- role
- tag
- parent
- default
however this order can be overridden with a plugin using the `cfct_single_match_order` hook.
Once a template match has been found, no other processing is done.
Supported Templates (Post Context)
- {dirname}-default.php – Used when there are no other templates that match for a given post/page.
- author-{username}.php – Used when a user with that username authors a post/page. For example, a template with a file name of
author-jsmith.phpwould be used for a poat/page by userjsmith. Any WordPres username can take the place of {username} in the file name. - cat-{slug}.php – Used when a post is in 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. - meta-{key}.php – Used when there is a custom field for the post/page matching the key listed in the file name. This is useful if you want to be able to flag posts as “photo” or similar, and give those posts some custom treatment. In this example, you could add a custom field of “photo” with a value of the URL of the image to a post/page and it would use a template of
meta-photo.phpif that template exists. The value does not matter in this match. - meta-{key}-{value}.php – Used when there is a custom field for the post/page matching the key and value listed in the file name. This is useful if you want to be able to flag posts as “featured” or similar, and give those posts some custom treatment. In this example, you could add a custom field of “featured” with a value of “yes” to a post/page and it would use a template of
meta-featured-yes.phpif that template exists. - page.php – Used when the content is being displayed is a page (not a post).
- parent-{slug}.php – Used when a page is a child page of a specific parent page. The page is matched by the “slug” – for example a page under a parent page with slug of “example” could use a template of
parent-example.php. - role-{role}.php – Used when a post/page is authored by a user with a particular role. The {role} is an all lowercase representation of the role string – for example, an author with an “Administrator” role might use a template of
role-administrator.php. This is primarily useful if you have a set of authors that are given a Contributor role; or a Guest Columnist role or similar. Any WordPress role can take the place of {role} in the file name. - tag-{slug}.php – Used when a post has a certain tag applied to it. The tag is matched by the “slug” – for example a post with tag “Reference” (with a tag slug of “reference”) could use a template of
tag-reference.php.
Create templates with names using these patterns and place them into the directories (content, excerpt) that use the Post Context. The templates will be used when a situation arises matching their named condition.
This has been an overview of the Post Context of the Carrington CMS theme framework for WordPress. You may want to take a look at the General Context and the Comment Context next.
Community additions to the documentation and resources for Carrington (including this page) are very welcome.
Categories: Development
Hi, thanks for the great documentation with examples and all. Much appreciated!
I am wondering about something that many others might be: how to change the post template when viewing the frontpage. I know that a template named home.php in posts/ will change the larger page structure, but it seems to call content/content-default.php. I tried dropping a home.php variant in content/ but it does not get selected.
I often want posts on the frontpage to be more stripped down, with more detail in the index or single views. So this functionality would be great. Thanks!
by Trevor on Aug 11, 2009 at 6:22 pm
home.php isn’t a supported template name in the Post context, that’s supported in the General context. You should create a custom loop (loop/home.php) and call the specific content template you want to use on the home page inside that loop file:
cfct_template_file('content', 'home');or, more likely:
cfct_template_file('excerpt', 'home');as desired.
by Alex King on Aug 11, 2009 at 6:41 pm
Wow, thank you for doing this.
by Ryan on Aug 15, 2009 at 10:53 pm
Hi Alex, I would like to be able to have an excerpt under my post title when they are opened through the category. So for example if my category is job techniques and it is clicked, I want my post called Wowing employers to have the excerpt show under the title and then a read more option which would then show the whole post. I’ve searched for various ways of doing this but have yet to have any success. I would definitely appreciate some help on this.
Thank you.
by Stephanie on Feb 3, 2010 at 1:46 pm
This looked amazing at first glance until I read the readme under /pages which essentially says “we don’t do pages”. it’s a problem because my CMS architecture is entirely built on a nested page structure (which makes sense, right).
by Rod on May 5, 2010 at 7:10 pm
Hi Rod, sorry for any confusion but Carrington theme does support pages. It’s WordPress that doesn’t support pages in sub-directories. Hopefully the README’s explain this clearly.
by Devin Reams on Sep 15, 2010 at 11:13 am
Hi Alex, love the framework. Also saw you speak at WordCamp Boulder a couple weeks ago. Good stuff.
How do you recommend handling custom post types with the Carrington Theme? I’m building a site now that utilizes several custom post types but they don’t use categories, tags or specific meta keys that would allow Carrington to distinguish them.
Many thanks.
by Dallas Johnson on Jul 21, 2010 at 11:23 am
I depends on what you want to do, but the type-*.php templates should be very useful for you.
by Alex King on Aug 2, 2010 at 8:39 am