Templates - Theme Reference - 0.11.3
The first thing you will probably want to do with your new theme is change one or more of the built-in templates. Templates are what control the content you see on your Store: they define the HTML layout as well as the data content you want to show. There are a few kinds of template - each serving a different purpose. Which ones you customise will depend on what you want to achieve.
Pages
Page-level templates are templates that are output as the content of the entire page between the header and footer. They correspond to the page that the user is visiting. Some examples are, the home page, the product page, the search page, the cart page etc.
Theme Templates
On the Related tab of your new theme, you will see a section for Theme Templates.
Create a new Theme Template to customise one of the pages.
The two important pieces of data required here are Key and Content.
The Key tells the theme engine what template this is. For all page-level templates, it must start with pages/. Then for the specific page types you must specify the exact name.
For example, to customise the Home page, the key must be: pages/home
Keys must be unique for a Theme, ie you can’t have multiple records with the key: pages/home
The Content specifies what will show for that template. You can supply any HTML content (including CSS and Javascript if you need, though that’s not recommended). You can also use Liquid code to create smart templates that can access your data. For more information see the Liquid Reference section in our documentation.
| Page | Key |
| account | pages/account |
| article | pages/article |
| article_category | pages/article_category |
| auth/confirmation/pending | pages/auth/confirmation/pending |
| auth/confirmation/resend | pages/auth/confirmation/resend |
| auth/invitation/accept | pages/auth/invitation/accept |
| auth/invitation/pending | pages/auth/invitation/pending |
| auth/login | pages/auth/login |
| auth/password/forgot | pages/auth/password/forgot |
| auth/password/reset | pages/auth/password/reset |
| auth/register | pages/auth/register |
| cart | pages/cart |
| cart.js | pages/cart.js |
| home | pages/home |
| location | pages/location |
| locations | pages/locations |
| maintenance | pages/maintenance |
| order | pages/order |
| page | pages/page |
| voucher | pages/voucher |
Previewing
Once you have added a new template for your theme, click the the “Click to Preview on Site” link on the Theme detail view to open your theme on your site. Note that this does not activate the theme on your site. Only people who follow that link (including anyone you share it with) will see the preview.
Here is our new theme being previewed on our Store. We are on the home page here, and you can see our new home page template being shown.
You can also see the preview bar at the top. This serves to confirm that you are previewing a theme on the Store, and allows you to switch between the preview theme, your normal theme (if there is one), and the built-in theme. This is a handy way to compare how your theme compares to other themes.
Content Blocks
The second type of template you can customise are the content block templates. Content block templates are the templates used to show the various types of content blocks you use on your site. For instance, if you use a slideshow content block on your home page, it will be rendered using the built-in slideshow template. If you want to change how the slideshow looks or works, you can now customise it, or any of the other content blocks.
You can customise any of the built-in content blocks:
| Content Block | Key |
| Container | blocks/container |
| Featured Articles | blocks/featured_articles |
| Featured Product Categories | blocks/featured_categories |
| Featured Pages | blocks/featured_pages |
| Featured Products | blocks/featured_products |
| Image beside text | blocks/image_beside_text |
| Image with text overlay | blocks/image_with_text_overlay |
| Image | blocks/image |
| Media | blocks/media |
| No Styling | blocks/html |
| Slideshow | blocks/slideshow |
| Text | blocks/text |
| Video | blocks/video |
You could also create your own custom content blocks. For example, if you wanted to create a new content block to render a widget, you would add an item to the Content_Block__c.Template__c picklist and give it the value widget. Then create a theme template with key blocks/widget to render your new content block.
Content block templates are created the same way as page templates. The only difference is that the key must start with blocks/ and must correspond to one of the Content Block template entries in the Content_Block__c.Template__c picklist.
Snippets
The final template type is Snippets. Snippets are reusable templates you can load from any other template. For example, you may have a header that you want to use on each page. You can create a snippet for this as follows.
Create a new theme template with the key snippets/page_header and whatever content you want to be in your page header. Note that the key must start with snippets/ but the rest of it can be whatever you like as long as it’s unique for the theme.
To use this snippet from another liquid template, use the following liquid code:
{% render "page_header" %}
You’ll note that the sample snippet we created calls a liquid variable title. The variable will be empty unless we pass a value in for it as follows:
{% render "page_header", title: "My Title" %}
Let’s update our home page template to use the header to use our new snippet.
When we preview it we now see our new snippet is showing.
You can create any number of snippets, and load them from any other template, including other snippets. However, don’t try to load a snippet into itself - you’ll cause an infinite loop and crash your site.
That rounds it up for the three types of templates: pages, blocks, and snippets.
Next up: Localisation with Theme Locales.
Back to Documentation