• Support for custom taxonomies within the general context
• Added support for custom post type archive pages in general context
• Support for post formats in the single context
• Relies on features in WordPress 3.1
• Implemented checked() and selected() functions for options
• Added PHP doc blocks
• E_NOTICE clean
• Updated some variable names

The new version is tagged and available at in our public SVN repository on Google Code.

You can replace the carrington-core directory in any Carrington theme with this new version to take advantage of these new features.

• Added support for custom post types (WordPress 3.0)
• Support for child themes (including adding templates and plugins in child themes that do not exist in the parent theme)
• Allow custom functions to be filtered into the Single and Comment template selection process (already supported in General context selection)
• home.php is now only used in is_home() situations, not is_front_page() (reverses feature requested and added in v. 2.5)

Other changes:

• Make the posts_per_page setting work as intended (only on initial query)
• Support for nesting templates inside sub-directories in misc/ and forms/
• Removed use of deprecated function `get_the_author_ID`. Replaced with 2.8 `get_the_author_meta` (since 2.8.0). Users of versions of WordPress prior to 2.8.0 should be aware this change will cause problems for them.
• Define required Carrington settings in a more forgiving way, making it easier to use just part of Carrington on a site when desired
• Make gallery settings (implemented in CSS) specific to each gallery
• Added changelog

Get the Carrington Core 3.0 release from the public SVN directory:

http://carrington.googlecode.com/svn/framework/tags/3.0

Child theme support is getting broader testing and is working well from what we’ve seen. An updated release of Carrington is probably due in the near future. If you’re seeing any issues with child themes with the latest Carrington core code, please open a ticket.

You can grab the latest from SVN on Google Code. Then simply replace the carrington-core directory in your theme with new version you have checked out from:

http://carrington.googlecode.com/svn/framework/trunk

and that should do it.

Note that the way child theme support is implemented, your child theme can add new templates to your theme as well as overriding existing templates. I think this is necessary for Carrington – it allows you to create custom templates for your specific site and have them upgrade cleanly via the child theme.

Feedback welcome.

UPDATE:

The steps to test if you want to make a child theme for a Carrington theme (before this support is rolled out in new releases):

1. Download the framework from SVN using the URL above and replace the carrington-core directory in your parent theme.
2. Create your child theme (which can include new Carrington templates).

That’s it.

It really depends on the needs of your site/theme. Carrington is all about making it easy for you to build the custom design and features needed for a specific site and set of content. If you look at the features of the Carrington framework and think “why would someone need that?”, then it probably isn’t for you.

Remember, WordPress can power more than just a blog – many of us use WordPress to build complex CMS web sites with a vast collection of sections, archives and content types. Most of the time when I describe how Carrington works to a fellow WordPress developer that builds rich CMS sites, they nod emphatically and “get it” right away.

Conversely, there are some folks who don’t see the need for the features provided by the Carrington framework. My guess is that if these people joined us at Crowd Favorite to help build one of our standard sites, they’d have a different view of the value of Carrington.

Once you understand how Carrington works, you may want to use it even if you’re just building a very simple blog or web site. It isn’t harder than any other theme techniques and provides for much greater flexibility for the future.

There is a learning curve. Carrington introduces new concepts and features to WordPress themes. If you don’t want/need the customization ability provided by Carrington, it may not be the best option for you.

How do I create a child theme from Carrington JAM?

This is actually the wrong question. You don’t create a child theme from Carrington JAM because Carrington JAM isn’t a parent theme. JAM is a Carrington file and folder skeleton to help you easily get started using the concepts in the Carrington framework so you can create a theme of your own.

Remember, Carrington is a real framework like Rails for Ruby and Django for Python. The theme you create from Carrington JAM is your own theme, just like the application you build with Ruby on Rails is your own application.

If I really want to can I create a child theme for Carrington Blog/Text/Mobile?

Yes, any theme in WordPress can be a parent theme. You can read a tutorial about how to do this here. There are some limitations of how parent themes work in WordPress, so those are also shared by Carrington themes.

I think it would be great if someone would like to take an in-depth look at creating child themes from Carrington and created an FAQ/tutorial. Please let me know if you create one.

If it turns out some changes are needed to Carrington, we’ll certainly consider them.

How do I upgrade the theme I built on Carrington?

Like any good development framework, the framework is separate from the product itself. The Carrington framework resides in the carrington-core directory and can be upgraded separately from the rest of your Carrington-based theme when a new version of the core Carrington framework is available.

With all of the template files, how do I tell what is getting loaded from where?

Carrington includes a function to show the file location of each included file. Simply open up the functions.php file in your editor and change this code:

define('CFCT_DEBUG', false);

to:

define('CFCT_DEBUG', true);

and you will see file paths appear all throughout the theme. This makes it very easy to see what part of the theme is comprised of which template(s).

Can I use just part of Carrington?

Absolutely. Remember, Carrington is a 100% additive framework. You can bring in Carrington for just your site header, just post content, comments, etc. All you have to do is create the appropriate folder and file combinations where you want to use Carrington, and call the appropriate function (cfct_header(), cfct_content(), etc.) to invoke Carrington’s selection of a template from that folder.

How do I use a custom taxonomy with Carrington?

It’s common to use custom taxonomies when creating advanced CMS web sites. Carrington doesn’t try to guess your intentions with a custom taxonomy, instead you can teach it about your taxonomy.

Create functions that check for the named templates that you want to use with your custom taxonomy, then use the appropriate filters to add your function into the template selection used by Carrington. You can use the existing functions that work with tags as a guide.

How do I do XYZ in Carrington?

It obviously depends on what XYZ is, but it’s likely that you’d do it the way you would in any other theme. Since Carrington is a 100% additive framework, the standard way of doing anything in a WordPress theme should work just fine. The areas in which you can take advantage of additional Carrington functionality are around conditional presentation and display of content, data, etc.

I find Carrington compelling, but I’m having trouble getting started – how can I get help?

I recommend reading the documentation linked on the Developers page on this site, and the README files in each directory in our Carrington themes and participating community support forums. Hopefully this information will be enough to get people going in most situations.

If you need additional help, you can also call the WordPress HelpCenter and they can answer most Carrington questions you may have. Crowd Favorite also provides commercial Carrington consulting and support (generally needs to be scheduled about 3-5 days in advance).

I think I found a bug in Carrington, what do I do?

Bug reports are best added to the Issue tracker at Google Code. If you’re not sure it’s a bug you may want to discuss the issue in the forums first to confirm.

If the bug is security related, please contact us directly instead of posting it publicly.

1. A fix for a logical bug in the context detection function – now properly selects the “home” context in some cases where it didn’t previously.
2. The addition of a filter to allow the available files to be provided by code rather than looking at directory contents.

If you wish to upgrade a Carrington-based theme to the latest core, you can do so by just replacing the “carrington-core” directory.

Get the Carrington Core 2.5 release from the public SVN directory:

http://carrington.googlecode.com/svn/framework/tags/2.5

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:

1. author
2. meta
3. category
4. role
5. tag
6. parent
7. 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.php would be used for a poat/page by user jsmith. 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.php if 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.php if 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.

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.

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.