Building a Theme for Spiffy Stores

From Spiffy Stores Knowledge Base

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

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