View source for 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:

<pre>
collection.grid.liquid
product.long.liquid
</pre>

Use the query parameter <code>?view=&lt;view&gt;</code> in a URL to load an alternate template.

=== Folder / Asset Structure ===

A recommended structure for your theme:

<pre>
/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)
</pre>

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 <code>theme.liquid</code>.
# '''Use Liquid syntax''' – Combine HTML and Liquid code to display dynamic store data.
# '''Define templates''' – Create files such as <code>index.liquid</code>, <code>product.liquid</code>, 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: <code>{{ ... }}</code>
* Logic blocks: <code>{% if ... %} ... {% endif %}</code>, <code>{% for ... %} ... {% endfor %}</code>
* Filters: <code>{{ product.title | upcase }}</code>

=== Platform-Specific Helpers ===

* '''Global assets''' – Include common JS/CSS via:

<pre>
{{ 'filename.js' | global_asset_url | script_tag }}
</pre>

See [[Using Global Javascript Assets]].

* '''Collection navigation example''' – On a product page:

<pre>
{% 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 %}
</pre>

See [[Liquid Collection Navigation]].

* '''URL helper''' – Maintain collection context:

<pre>
{{ product.url | within: collection }}
</pre>

=== Theme Settings ===

Theme settings (colours, fonts, etc.) are configurable via the Toolbox and referenced in templates with <code>{{ settings.&lt;name&gt; }}</code>.

== Assets, Scripts & Performance ==

* Use <code>global_asset_url</code> 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 (<code>{% paginate %}</code>) 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. <code>product.featured.liquid</code>).
* Use snippets for headers, footers, and reusable components.
* Add comments and README documentation.
* Test responsive layouts thoroughly.
* Use <code>global_asset_url</code> helpers.
* Include SEO tags:
<syntaxhighlight lang="html">
<meta name="description" content="{{ header.description }}">
<meta name="keywords" content="{{ header.keywords }}">
</syntaxhighlight>
See [https://www.spiffystores.net.au/kb/Liquid_Template_Variables_-_header Liquid Template Variables – header].
* Maintain version control (e.g. Git) and backups.

== Example: Previous / Next Product Navigation ==

Add navigation to <code>product.liquid</code>:

<syntaxhighlight lang="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 %}
</syntaxhighlight>

Ensure product links in collections use:
<syntaxhighlight lang="liquid">
{{ product.url | within: collection }}
</syntaxhighlight>

== 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]]