Template File Hierarchy
From Habari Project
Themes in Habari are constructed from several template files. Each template potentially corresponds to a type of data and the amount of data that is displayed.
A "post" refers to an atomic published unit. There are different types of posts in the core Habari software. These types are called "content-types".
Habari supports different template engines. Out of the box, the only engine provided is the RawPHPEngine. This template engine is a basic engine that executes native PHP, using PHP itself as a template language. An alternative engine might support the Smarty template language.
Because different engines will require different file extensions (PHP needs ".php" and Smarty needs ".tpl", for example) template files are always referred to in Habari without file extension. It is the job of the engine to apply the appropriate extension to the template name.
"entry" is post content-type that indicates that the post flows chronologically with other entries. An "entry" would make up the bulk of daily blog posts.
"page" is a post content-type that indicates that the post is separate from the chronological flow.
Additional content-types may be defined in the database or in plugins for different purposes. The style of the output page may be affected by the content-type of the post. A theme should accommodate these additional content-types by providing distinct templates for those content-types or by providing generic templates that are not specific to any single content type.
Use in Themes
The use of content-types in themes allows templates to exist for each content-type.
A post of content-type "entry" will be displayed using the entry.single template. Likewise, a post of content-type "page" will be displayed using the page.single template.
Any request to display output will either be attributed to a single post or multiple posts. When requesting "posts with a certain tag", multiple posts would be returned (even if only one post exists with that tag). When requesting a specific post, a single post would be returned.
A template file containing the text "single" is used to display a single post. The template will be provided with only a single post item for display.
A template file containing the text "multiple" is used to display multiple posts. This template should expect to receive a collection of post items for display. It is possible that this collection will contain only a single post; but since it's a (one-member) collection it will use the "multiple" template file.
Use in Themes
When a request is made for a group of posts, Habari will attempt to find the best matching template name using a "multiple" template. For example, when displaying multiple posts of content-type "entry", Habari will look for the entry.multiple template.
If only one post of content-type "entry" is requested, Habari will look for the entry.single template.
If multiple posts are requested, but only one post exists to fill the request, Habari should still use the entry.multiple template, because that was the request. It should not use entry.single unless only a single post was specifically requested.
A couple of requests have unique templates that Habari can display specifically for those requests.
404 Error will cause Habari to display results using the 404 template. Put something meaning for visitors when URL can't be reached.
The request of a search page will cause Habari to display results using the search template. The search template should act like a "multiple" template: it should expect to receive a collection of items, possibly of different content-types. The collection of items to display in the search template may contain zero, one, or more items.
The request of the home page will cause Habari to display results using the home template. The home template can be configured to display zero, one, or more items of any content-type, as you see fit.
When requesting any specific post,
1. Habari will either check for a template that is specific to that post's id, using the content-type of the post. For example, when requesting an entry with the id #35, Habari will attempt to display that single post's content using the entry.35 template. For a page with id #36, Habari would attempt to use page.36 template.
2. Or Habari will check for a template that is specific to that post's slug, using the content-type of the post. For example, when requesting an entry with the slug "foo", Habari will attempt to display that single post's content using the entry.foo template. For a page with slug "bar", Habari would attempt to use page.bar template.
When requesting any post with a specific tag, Habari will check for a template that is specific to that tag, using the content-type of the post. For example, when requesting an entry with tag "foo", Habari will attempt to display that post's content using the entry.tag.foo template. For a page with tag "bar", Habari would attempt to use page.tag.bar template.
When Habari fails to find the most specific template needed to display content for a request, it searches for the next less-specific template that could display that content.
For example, when failing to find an explicit template for entry #35 (entry.35), Habari would then look for a "single" type template for that content type. In this case, the entry.single template.
Each request has a chain of templates that it tries, getting more generic as the possible templates fail to exist. Eventually, Habari attempts to display the content using the home template. The home template is the minimum required template for a functioning theme. (That is to say, a theme may have only a home template file, which will be used to display all content.)
The failover order for any request is determined in the core system Theme class (not necessarily the user Theme class), and is specific to the type of request made. The failover order can be overridden by using a custom Theme class, but this is not required for failover to work as described.
List of supported filenames
Below is the list of files that Habari will look for in order based on the type of request. The template engine will likely use the first file listed that exists, and will continue through the list to the end until it finds a matching file for that request.
These substitutions should be used for elements of the template name that begin with a dollar sign:
- The content type of the post, usually entry or page
- The id of the post
- The requested tag.
- The requested year.
- The requested month.
- The requested day.
Display the homepage (/)
Display an entry or a page (/first-post)
Display entries by tag (/tag/deleteme)
Display search results (/search/hello+world)
Display entries by date (/2007/12/02)