What is Carrington?
- A collection of elegant, high-end WordPress themes for end-users.
- A designer and developer friendly CMS theme framework for WordPress.
- A set of best practices for theme organization.
Basic Framework Concept
Carrington is a CMS theme framework that virtually eliminates the need for custom conditional code in themes. Instead, template naming conventions along with the Carrington engine replace the need for this conditional code.
Theme functionality is broken up into thoughtfully crafted abstractions to enable customizations at different levels (the loop, the post/page content, comments, etc.) and the Carrington engine chooses which template to be used for each segment of the theme.
The abstractions and supported template types are designed to easily handle most of the customization scenarios we commonly see without the need to write custom code to use them.
Context and Templates
WordPress provides a number of functions to help you determine what type of view a theme is showing. These include:
is_home()is_single()is_page()is_archive()in_category()- etc.
Carrington abstracts these to deduce a “context” that is used when selecting a template. There are three context types used by the Carrington framework:
- Comment (dirs: comment)
- Content (dirs: content, excerpt)
- General (dirs: attachment, comments, footer, header, loop, posts, sidebar, single)
Each directory implements one of these contexts for selecting the appropriate template to use. Templates are used in page views based on how they match the given context(s) for the page and content.
Read about the options available in each directory in the README file for that directory.
Note: “default.php” is a supported default file name for all directories, however we have found in real world usage that {dirname}-default.php is a preferable naming system. When you have a half-dozen “defaultphp” files open in your favorite text editor, telling them apart in the file list can be more difficult than it should be.
Theme Organization
WordPress themes generally have a file structure similar to this:
- 404.php
- archive.php
- archives.php
- […]
- sidebar.php
- single.php
- style.css
While this organization works well in many instances, it doesn’t well support the concept of atomic elements that are combined to create a theme. For example, a representation of just a post’s content, or just a comment, is not represented here.
Carrington respects the supported WordPress file naming conventions (for example get_header() will still work), but eschews them in favor of an organizational structure that better suits the abstraction and customization commonly needed for a WordPress theme.
Template files are layered into each other using the following basic approach:
- top level templates that include
- common elements like a header, footer and sidebar along with a
- loop that includes
- atomic post/page content or excerpt templates and, where appropriate, a
- comments area template that includes
- atomic template for comments and a
- template for the comment form
Actions and Filters
Because Carrington is as much a theme framework as a theme itself, it includes a core set of functions that enable the override template hierarchy. These functions include actions and filters where appropriate so that their functionality can be customized and overridden as needed. These actions and filters use the same hook and filter system used in the WordPress core.
Filters
Actions
cfct_settings_form - allows you to add your own fields to the Carrington Settings form (left for compatibility` - recommend using _top and _bottom as needed instead of this).cfct_settings_form_top - allows you to add your own fields at the top of the Carrington Settings form.cfct_settings_form_bottom - allows you to add your own fields at the bottom of the Carrington Settings form.cfct_settings_form_after - allows you to add your content after the Carrington Settings form. Useful if you want to add a second form to the page, or some other content.cfct_update_settings - allows you to take action when the Carrington settings are being saved (perhaps to also save fields you’ve added in the cfct_settings_form action).
Plugins
Any .php files in the plugins/ directory will be automatically loaded by Carrington. This is a great way to bundle in custom functions or to hook into Carrington’s actions or filters and be able to distribute everything as a single theme package.
File Structure
image/
This directory holds templates for images/attachments.
General Context
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:
- author
- role
- category
- tag
- single
- default (home, search, archivem 404, etc.)
This can be altered using the cfct_general_match_order hook.
Supported Templates
- {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.
- 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.
- *role-{rolename}.php
- 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.
Close attachment/
carrington-core/
Overview
This directory contains Carrington’s custom features and functionality.
Supported Override Filenames
File Descriptions
You do not need to do anything with files in this folder; they should remain as-is.
Close carrington-core/
content/
This directory holds the templates for displaying a post. Typically this will be the full post with title, meta information (date, categories, tags, author, etc.) and the full output of the_content().
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 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.
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
- {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.
Close content/
css/
Organizational folder for holding theme image files. You can reference these files using the built-in WordPress bloginfo() function like so:
<link rel="stylesheet" type="text/css"
href="<?php bloginfo('template_directory'); ?>/css/base.css" />
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close css/
error/
This directory holds templates for error conditions. WordPress supports the 404 error out of the box, but you may want to create additional error templates for other conditions (not authorized, etc.).
You can load an error template by using the following code:
cfct_error('not-authorized.php');
Example File Descriptions
- 404.php - used for “File not Found” errors.
- exit.php - used to display a message when exiting on some error condition.
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close error/
excerpt/
(This information is very similar to the content/)
This directory holds the templates for displaying a the excerpt for a post. Typically this will include the title and some sub-set of meta information (date, categories, tags, author, etc.) and the full output of the_content().
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 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.
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
- {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.
Close excerpt/
forms/
Overview
This directory holds forms that may be used in various places throughout the theme.
These forms can be included in other theme files using the following code:
<?php cfct_form('comment'); ?>
Where comment.php is the name of the file in the forms/ directory that you want to include.
Example File Descriptions
Included by default are the “post comment” form (comment.php) and the “search” form (search.php). Create as many forms as you like and store them here to keep them organized.
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close forms/
functions/
This directory contains custom features and functionality for this particular Carrington based theme.
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close functions/
img/
Organizational folder for holding theme image files.
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close img/
js/
Organizational folder for holding theme JavaScript files.
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close js/
loop/
This directory contains files that do “the loop”. Generally the files in this directory will be included in a file from the posts/ or pages/ directory, and they will in turn include templates from the content/ or excerpt/ directories.
For example, you might want posts on a search results page to display differently that posts on an archive page. Here is how that page would be built:
- A page is identified as a search page - Carrington looks for a posts/search.php file and will fall back on a posts/default.php file if none is found.
- The posts/search.php file will include the header, footer and sidebar - and will also include a call to
cfct_loop() to include a loop.
- Since we don’t want to show the full posts in search results, the posts/search.php explicitly asks for a file from the excerpt/ directory to display the posts in the search results. It will use excerpt/search.php if that file exists, or fall back on excerpt/default.php if the custom file does not exist.
General Context
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:
- author
- role
- category
- tag
- single
- default (home, search, archivem 404, etc.)
This can be altered using the cfct_general_match_order hook.
Supported Templates
- {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.
- 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.
- *role-{rolename}.php
- 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.
Close loop/
misc/
This directory holds page fragments and snippets that you may want to use across multiple template files.
These files can be included in other theme files using the following code:
<?php cfct_misc('nav-posts'); ?>
Where nav-posts.php is the name of the file in the misc/ directory that you want to include.
Example File Descriptions
- banner.php - This is used by Carrington to display a message that is passed to it.
- nav-posts.php - This is standard paging for posts pages.
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close misc/
pages/
WP doesn’t support page templates in nested folders like this one, so page organization isn’t as clean as we’d like.
Create a page in the theme root:
File name: page-example.php
Note: We recommend prefixing all of your page files with ‘page-’ so that they are easily sorted together in your theme directory.
File contents:
<?php
/*
Template Name: Example Template
*/
if (__FILE__ == $_SERVER['SCRIPT_FILENAME']) { die(); }
if (CFCT_DEBUG) { cfct_banner(__FILE__); }
cfct_page('example');
?>
This will then load ‘example.php’ from the pages/ directory, keeping all of your actual page code nicely organized in one spot.
You can also add your page code to the page-example.php file you create in the theme root, but we’re hoping to get support for pages in a sub-directory in a future version of WordPress so we are starting with what we consider to be a “proper” organization structure now.
Supported Filenames
- pages-default.php (or default.php)
File Descriptions
A “default” template is required. You can create other templates as desired.
Close pages/
plugins/
Carrington supports plugins in the same conceptual manner as WordPress. Carrington includes several hooks and filters so you can customize/override Carrington’s default behavior.
Any .php files placed in this directory will be auto-loaded and processed by Carrington.
This is the recommended way to interact with the hooks and filters provided by Carrington so that they can be easily distributed with the theme.
This directory is not used by the Carrington engine (template naming conventions are not supported), it is provided solely for convenience and for better organization of these files.
Close plugins/
posts/
The files in this directory are “top level” templates for pages in WordPress that show multiple posts at once. These files should call the_header(), the_sidebar(), the_footer() and cfct_loop() to include the other parts of the page.
The file from this directory that will be used is chosen based on the current page context.
You can explicitly decide which loop/ to use from these templates by passing it in as so:
cfct_template_file('loop', 'example');
which would use loop/example.php for the loop.
General Context
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:
- author
- role
- category
- tag
- single
- default (home, search, archivem 404, etc.)
This can be altered using the cfct_general_match_order hook.
Supported Templates
- {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.
- 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.
- *role-{rolename}.php
- 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.
Close posts/
single/
This directory holds top level templates for “single” post pages. These files should call the_header(), the_sidebar(), the_footer(), cfct_loop() and cfct_comments() to include the other parts of the page.
All General Context template filenames apply here, but in reality only single.php and single-{Content Context}.php files will be used as the General Context must fall to “single” to look for templates here.
General Context
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:
- author
- role
- category
- tag
- single
- default (home, search, archivem 404, etc.)
This can be altered using the cfct_general_match_order hook.
Supported Templates
- {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.
- 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.
- *role-{rolename}.php
- 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.
Close single/
Tips
There is extra processing associated with the file system and context checks that Carrington requires. Because of this, use of a caching plugin is recommended.
