Who should use the Carrington framework?

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.

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:

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.