Building a Theme for Spiffy Stores
From Spiffy Stores Knowledge Base
Contents
- 1 Building a Theme for Spiffy Stores
- 1.1 Overview
- 1.2 Theme Structure & Required Templates
- 1.3 Getting Started: Creating a Theme
- 1.4 Liquid Syntax & Platform-Specific Features
- 1.5 Assets, Scripts & Performance
- 1.6 Packaging & Distribution
- 1.7 Best Practices & Tips
- 1.8 Example: Previous / Next Product Navigation
- 1.9 Migration & Update Considerations
- 1.10 Summary
- 1.11 References
Building a Theme for Spiffy Stores
This article describes how to create and customise a theme for the Spiffy Stores e-commerce platform using the templating system (HTML + CSS + Liquid tags). This system is analogous to building a Shopify theme, and uses the Liquid syntax.
Overview
A theme in Spiffy Stores is essentially a set of HTML/CSS/Liquid template files, plus related assets (images, JavaScript, fonts), packaged (typically as a ZIP) or edited via the store's Toolbox theme editor.
Spiffy Stores uses Liquid tags to render dynamic store data (products, collections, pages, blogs) inside the templates. For background on Liquid syntax, see [[Liquid Basics].
Because many developers are already familiar with Shopify themes, it is fair to say the workflow is very similar. However, there are platform-specific differences such as template names, theme settings and asset helpers.
Theme Structure & Required Templates
The base theme file set for Spiffy Stores typically includes the following templates:
- theme.liquid — controls the overall layout and look of the site (header, footer, etc.)
- index.liquid — layout for the home page
- collection.liquid — layout for a collection page
- list-collections.liquid — layout for the collections index
- blog.liquid — blog listing layout
- article.liquid — single blog article layout
- cart.liquid — shopping cart page
- product.liquid — single product page
- search.liquid — search results page
- 404.liquid — “not found” page
- page.liquid — general page (e.g. About, Contact)
You can also create alternative templates for specific layouts by appending a view name, for example:
collection.grid.liquid product.long.liquid
Use the query parameter ?view=<view>
in a URL to load an alternate template.
Folder / Asset Structure
A recommended structure for your theme:
/assets/ (CSS, JS, fonts, images) /layouts/ (theme.liquid) /templates/ (index.liquid, product.liquid, etc) /snippets/ (header.liquid, footer.liquid) /config/ (theme settings file if used)
Themes are usually uploaded as a ZIP archive or edited directly through the Toolbox. Editing via WebDAV is also supported.
Getting Started: Creating a Theme
- Choose a starting template – Pick a base theme from the Spiffy Theme Gallery, apply it, then download it as your starting point.
- Edit via the Toolbox or WebDAV – In the admin, go to Design & Assets → Theme Editor, or connect via WebDAV to edit locally.
- Create theme.liquid – This is the master layout file including header, footer, and main content placeholder.
- Add CSS and JavaScript – Place these in the assets folder and link to them from
theme.liquid
. - Use Liquid syntax – Combine HTML and Liquid code to display dynamic store data.
- Define templates – Create files such as
index.liquid
,product.liquid
, etc., with appropriate Liquid objects. - Upload and test – Save and apply the theme in your store’s Toolbox, then preview all pages.
- Package for distribution – If releasing publicly, compress your theme and include documentation.
Liquid Syntax & Platform-Specific Features
Since Spiffy Stores uses Liquid (the same templating language as Shopify), familiar concepts like objects, tags, filters, loops and conditionals apply.
Basic Syntax
- Output values:
Template:...
- Logic blocks:
{% if ... %} ... {% endif %}
,{% for ... %} ... {% endfor %}
- Filters:
Template:Product.title
Platform-Specific Helpers
- Global assets – Include common JS/CSS via:
{{ 'filename.js' | global_asset_url | script_tag }}
See Using Global Javascript Assets.
- Collection navigation example – On a product page:
{% if collection %} {% if collection.previous_product %} {{ 'Previous Product' | link_to: collection.previous_product }} {% endif %} {% if collection.next_product %} {{ 'Next Product' | link_to: collection.next_product }} {% endif %} {% endif %}
See Liquid Collection Navigation.
- URL helper – Maintain collection context:
{{ product.url | within: collection }}
Theme Settings
Theme settings (colours, fonts, etc.) are configurable via the Toolbox and referenced in templates with {{ settings.<name> }}
.
Assets, Scripts & Performance
- Use
global_asset_url
to link to hosted JS/CSS libraries maintained by Spiffy Stores. - Combine and minify CSS/JS files.
- Optimise images and ensure responsive design.
- Use pagination tags (
{% paginate %}
) for large collections.
Packaging & Distribution
When releasing a theme:
- Include all templates, snippets, assets, and documentation.
- Provide screenshots or demo links.
- Document installation and customisation instructions.
- Ensure browser and device compatibility.
- Provide version notes for updates.
Best Practices & Tips
- Start from an existing theme.
- Use meaningful template names (e.g.
product.featured.liquid
). - Use snippets for headers, footers, and reusable components.
- Add comments and README documentation.
- Test responsive layouts thoroughly.
- Use
global_asset_url
helpers. - Include SEO tags:
<meta name="description" content="{{ header.description }}"> <meta name="keywords" content="{{ header.keywords }}">
- Maintain version control (e.g. Git) and backups.
Add navigation to product.liquid
:
{% if collection %} <nav class="product-nav"> {% if collection.previous_product %} <a href="{{ collection.previous_product.url }}">← Previous: {{ collection.previous_product.title }}</a> {% endif %} {% if collection.next_product %} <a href="{{ collection.next_product.url }}">Next: {{ collection.next_product.title }} →</a> {% endif %} </nav> {% endif %}
Ensure product links in collections use:
{{ product.url | within: collection }}
Migration & Update Considerations
- Compare changes carefully when upgrading themes.
- Test for deprecated Liquid features.
- When migrating from Shopify, map template names and variables correctly.
- Provide clear upgrade paths for customised themes.
Summary
Developing a theme for Spiffy Stores involves working with HTML, CSS, and Liquid templates following Spiffy’s naming conventions and asset helpers. Start with a base theme, structure your files cleanly, test thoroughly, and use snippets and settings to create flexible, reusable designs.