Commit e24ffba7 authored by lucha's avatar lucha Committed by lechuck

removed a dozen of README.txt files from carrington blog theme

parent 0a5ae2e9
# Carrington CMS Theme Framework for WordPress
http://carringtontheme.com
by Crowd Favorite
http://crowdfavorite.com
Released under the GPL license
http://www.opensource.org/licenses/gpl-license.php
---
## Online Developer Resources
Please see the latest online developer resources for Carrington here:
http://carringtontheme.com/developers/
## What is Carrington?
1. A collection of elegant, high-end WordPress themes for end-users.
2. A designer and developer friendly CMS theme framework for WordPress.
3. 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:
1. Comment (dirs: comment)
2. Post (dirs: content, excerpt)
3. 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 overall page and the specific pieces of content being displayed.
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 "default.php" 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:
1. top level templates that include
2. common elements like a header, footer and sidebar along with a
3. loop that includes
4. atomic post/page content or excerpt templates and, where appropriate, a
5. comments area template that includes
6. atomic template for comments and a
7. template for the comment form
## Actions and Filters
The Carrington core is a theme framework, not a parent/child theme system. 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
- `cfct_context` - allows you to apply filters to the return value of the `cfct_context()` function; the function that checks to see what posts file, loop file, etc. to show.
- `cfct_filename` - filter the output of the `cfct_filename()` function.
- `cfct_general_match_order` - set the order in which general templates are chosen (make it check for a cat-general template ahead of a cat-news template, etc.).
- `cfct_choose_general_template` - filter the output of the `cfct_choose_general_template()` function (the selected general template).
- `cfct_single_match_order` - set the order in which single and content templates are chosen (make it check for author templates ahead of meta template, etc.).
- `cfct_choose_single_template` - filter the output of the `cfct_choose_single_template()` function (the selected single template).
- `cfct_choose_content_template` - filter the output of the `cfct_choose_content_template()` function (the selected content template).
- `cfct_comment_match_order` - set the order in which content templates are chosen (make it check for role templates ahead of user templates, etc.).
- `cfct_choose_comment_template` - filter the output of the `cfct_choose_comment_template()` function (the selected comment template).
- `cfct_meta_templates` - filter the return value of the `cfct_meta_templates()` function (change the list of files returned).
- `cfct_cat_templates` - filter the return value of the `cfct_cat_templates()` function (change the list of files returned).
- `cfct_tag_templates` - filter the return value of the `cfct_tag_templates()` function (change the list of files returned).
- `cfct_author_templates` - filter the return value of the `cfct_author_templates()` function (change the list of files returned).
- `cfct_role_templates` - filter the return value of the `cfct_role_templates()` function (change the list of files returned).
- `cfct_parent_templates` - filter the return value of the `cfct_role_templates()` function (change the list of files returned).
- `cfct_single_templates` - filter the return value of the `cfct_parent_templates()` function (change the list of files returned).
- `cfct_comment_templates` - filter the return value of the `cfct_single_templates()` function (change the list of files returned).
`cfct_post_gallery_columns` - set the number of columns to show in the gallery.
`gallery_style` - retained from the WP function code copied in and altered for gallery display.
`cfct_option_defaults` - allows you to set defaults (alter/add/etc.) for Carrington options.
`cfct_files_{path}` - allows you to define the available files for a path.
### 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.
---
## Tips
There is very minor extra processing associated with the file system and context checks that Carrington requires. This overhead is virtually unnoticeable, however the use of a caching plugin is recommended as a general best practice.
## 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:
1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)
This can be altered using the `cfct_general_match_order` hook.
### 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_.
## carrington-core/
### Overview
This directory contains Carrington's custom features and functionality.
### Supported Override Filenames
- (none)
### File Descriptions
You do not need to do anything with files in this folder; they should remain as-is.
## comment/
### Overview
This directory holds templates for displaying a comment in it's entirety. These templates do not hold the comment loop, or the "Comments" title or the form to allow commenting; they just show a single comment.
Typically these templates will be brought in to a template in _comments/_, but can also be used to display single comments as needed.
## Comment Context
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. meta
5. role
6. 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 WordPres username can take the place of {username} in the file name.
- *meta-{key}.php* - Used when there is a custom field for the comment matching the key listed in the file name. This is useful if you want to be able to flag comments as "tweetbacks" or similar, and give those posts some custom treatment. In this example, you could add a custom field of "tweetback" with a value of the URL of the Tweet and it would use a template of <code>meta-tweetback.php</code> 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 comment matching the key and value listed in the file name. This is useful if you want to be able to flag comments as "voted" (someone voting the post up or down) or similar, and give those posts some custom treatment. In this example, you could add a custom field of "voted" with a value of "up" or "down" with their comment and it would use a template of <code>meta-voted-up.php</code> or <code>meta-voted-down.php</code> if that template exists.
- *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.
\ No newline at end of file
## comments/
This directory holds templates for displaying the comment loop and the comment form - what is typically called in by WordPress's `comment_template()` function.
This level of abstraction us useful to be able to load in the comments and new comment form for a post/page via AJAX if desired.
## 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:
1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)
This can be altered using the `cfct_general_match_order` hook.
### 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_.
## 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()`.
## Post Context
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. type
5. role
6. tag
7. parent
8. 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 <code>author-jsmith.php</code> would be used for a poat/page by user <code>jsmith</code>. 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 <code>cat-general.php</code>.
- *type-{post_type}.php* - Used when a post belongs to a specific custom post type. The type is matched by the "post_type" property of the post. For example if you had a custom post type of <code>news</code>, you could use a template with the name <code>type-news.php</code>.
- *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 <code>meta-photo.php</code> 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 <code>meta-featured-yes.php</code> 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 <code>parent-example.php</code>.
- *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 <code>role-administrator.php</code>. 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 <code>tag-reference.php</code>.
## 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.
\ No newline at end of file
## 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.
\ No newline at end of file
## 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()`.
## Post Context
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. type
5. role
6. tag
7. parent
8. 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 <code>author-jsmith.php</code> would be used for a poat/page by user <code>jsmith</code>. 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 <code>cat-general.php</code>.
- *type-{post_type}.php* - Used when a post belongs to a specific custom post type. The type is matched by the "post_type" property of the post. For example if you had a custom post type of <code>news</code>, you could use a template with the name <code>type-news.php</code>.
- *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 <code>meta-photo.php</code> 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 <code>meta-featured-yes.php</code> 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 <code>parent-example.php</code>.
- *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 <code>role-administrator.php</code>. 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 <code>tag-reference.php</code>.
## footer/
The standard _footer.php_ file (included using the WordPress `get_footer()` function) in Carrington is set up to call the `cfct_footer()` function, which will choose the appropriate footer file from this directory - based on the context of the given page. This can be useful if you want to have pages to have a custom footer, or perhaps a certain category to have a custom footer.
## 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:
1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)
This can be altered using the `cfct_general_match_order` hook.
### 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_.
## 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.
\ No newline at end of file
## 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.
\ No newline at end of file
## header/
The standard _header.php_ file in Carrington is set up to call the `cfct_header()` function, which will choose the appropriate header file from this directory - based on the context of the given page. This can be useful if you want to have pages to have a custom header, or perhaps a certain category to have a custom header.
## 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:
1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)
This can be altered using the `cfct_general_match_order` hook.
### 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_.
## 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.
\ No newline at end of file
## 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.
\ No newline at end of file
## 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:
1. 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.
2. 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.
3. 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:
1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)
This can be altered using the `cfct_general_match_order` hook.
### 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_.
## 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.
\ No newline at end of file
## 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.
## 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.
\ No newline at end of file
## 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:
1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)
This can be altered using the `cfct_general_match_order` hook.
### 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_.
## sidebar/
This directory holds the sidebar files for the theme. The file from this directory that will be used is chosen based on the current page context.
## 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:
1. author
2. role
3. category
4. tag
5. single
6. default (home, search, archive, 404, etc.)
This can be altered using the `cfct_general_match_order` hook.
### 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_.
## 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-{Post Context}.php files will be used as the General Context must fall to "single" to look for templates here.