Building a Theme for Spiffy Stores

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

1. Choose a starting template – Pick a base theme from the Spiffy Theme Gallery, apply it, then download it as your starting point.
2. Edit via the Toolbox or WebDAV – In the admin, go to Design & Assets → Theme Editor, or connect via WebDAV to edit locally.
3. Create theme.liquid – This is the master layout file including header, footer, and main content placeholder.
4. Add CSS and JavaScript – Place these in the assets folder and link to them from theme.liquid.
5. Use Liquid syntax – Combine HTML and Liquid code to display dynamic store data.
6. Define templates – Create files such as index.liquid, product.liquid, etc., with appropriate Liquid objects.
7. Upload and test – Save and apply the theme in your store’s Toolbox, then preview all pages.
8. 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.

Example: Previous / Next Product Navigation

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.

References

• The Spiffy Theme Guide
• Using Global Javascript Assets
• Liquid Collection Navigation
• Liquid Variable Reference