Graffiti provides each theme with .view files so you can determine what is displayed on your site and how it is displayed.
Graffiti uses simple yet powerful templating system to display its site content. The .view files are accessible when you edit a theme.
The following are some important points about file structure in Graffiti.
- Each theme exists in its own folder in the /files/themes directory. Graffiti provides the file browser utility so you can upload files as necessary.
- Each theme must contain the following three files:
- layout.view - This file is responsible for the basic "shell" of a theme. For those of you familiar with ASP.Net, it is very similar to a master page.
- index.view - This file is responsible for rendering a list of posts. By default, this file includes the home page, all category pages, tag pages, and the search results page.
- post.view - This file is responsible for rendering a single post (single piece of content). If enabled, this file usually includes comments.
Graffiti requires a file naming convention for custom views that follows a logical pattern based on the portions of the site that are affected. Before using any default view files inside a theme, Graffiti makes sure that any customized view files exist for
the theme. If they do, Graffiti uses the customized view files instead of the three default views. This allows you to add support for custom views to your theme and leave the default views in place. Structuring a theme in this way allows a user to modify your
theme specific views without fear of breaking the default views on the site.
Here are some examples of how this works.
- Category.view - This file renders all of the category pages. It overrides index.view.
- Category-Name.view - If this file name matches a category in Graffiti, it is used to render that category. This files overrides both category.view and index.view.
- Category-Name.post.view - If this file name matches a category, it is used to render all of the individual post pages in the category. This file overrides post.view.
- Category-Name.Post-Name.view - If this file name matches a category and a post name, it is used to render the post. This is important because two posts can have the same name if they are in different categories. This file overrides both Category-Name.post.view
- Search.view - This file renders the search results in Graffiti. It overrides index.view.
- Post-Name.view - If this file name matches the name of a post, it is used to render the post. Post names are only unique per category, so for more explicit control you may want to consider Category-Name.Post-Name.view. This file overrides post.view.
- Page.view - If this file exists, Graffiti uses it to render any uncategorized posts. It overrides default post.view.
The overrides allow you to build your site and have complete control over each individual page. However, one of our other design goals is to remove the need to duplicate any of your design elements across multiple files. In addition, we wanted to provide designers
with an easy way to keep their view files very simple and lightweight. To accomplish this, we added a second set of overrides which can be used based on location.
Here are a couple of file examples:
- Home.Layout.view - When Graffiti finds this file in the current theme, it is used instead of Layout.view on the home page.
- Search.Layout.view - When Graffiti finds this file in the current theme, it is used instead of Layout.view on the search page.
- Category.Layout.view - When Graffiti finds this file in the current theme, it is used instead of Layout.view on all category pages.
- Category-Name.Layout.view - When Graffiti finds this file in the current theme, it is used instead of Layout.view on the current category page.
Finally, there is one additional set of file overrides. You can use templating syntax to accomplish similar tasks. The syntax takes the form of $FileName. The following files are available for you to use:
When Graffiti finds $FileName in any view, it attempts to load and render a view based on that name. In addition, Graffiti makes the same location-based overrides as described earlier.
Below are a couple of examples of $header:
Note: To limit looking up which files exist on every request, Graffiti caches known files in memory. This is a very big performance gain, but makes designing a new theme difficult. To get around this, you can turn off View caching by changing on the
Site Configuration settings page. Just remember to set it back to true before you deploy a site into production.
- If Graffiti encounters $header in any view, it will try to load and render a view named header.view in the current theme.
- If $header was requested from the home page, Graffiti first tries home.header.view.
- If $header was used on a category page named Sample, it first tries find sample.header.view, then category.Header.view, and finally header.view.