Building a Theme for Spiffy Stores: Difference between revisions

From Spiffy Stores Knowledge Base
Jump to: navigation, search
Admin (talk | contribs)
mNo edit summary
Admin (talk | contribs)
 
(5 intermediate revisions by the same user not shown)
Line 34: Line 34:
</pre>
</pre>


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


=== Folder / Asset Structure ===
=== Folder / Asset Structure ===


A recommended structure for your theme:
A recommended structure for your theme:
<syntaxhighlight lang="text">
 
<pre>
/assets/        (CSS, JS, fonts, images)
/assets/        (CSS, JS, fonts, images)
/layouts/        (theme.liquid)
/layouts/        (theme.liquid)
Line 45: Line 46:
/snippets/      (header.liquid, footer.liquid)
/snippets/      (header.liquid, footer.liquid)
/config/        (theme settings file if used)
/config/        (theme settings file if used)
</syntaxhighlight>
</pre>


Themes are usually uploaded as a ZIP archive or edited directly through the Toolbox. Editing via WebDAV is also supported.
Themes are usually uploaded as a ZIP archive or edited directly through the Toolbox. Editing via WebDAV is also supported.
Line 62: Line 63:
== Liquid Syntax & Platform-Specific Features ==
== 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.
Since Spiffy Stores uses Liquid (the same templating language as Shopify), familiar concepts like objects, tags, filters, loops and conditionals apply.


=== Basic Syntax ===
=== Basic Syntax ===
Line 73: Line 74:


* '''Global assets''' – Include common JS/CSS via:
* '''Global assets''' – Include common JS/CSS via:
<syntaxhighlight lang="liquid">
 
<pre>
{{ 'filename.js' | global_asset_url | script_tag }}
{{ 'filename.js' | global_asset_url | script_tag }}
</syntaxhighlight>
</pre>
See [https://www.spiffystores.net.au/kb/Using_Global_Javascript_Assets Using Global Javascript Assets].
 
See [[Using Global Javascript Assets]].


* '''Collection navigation example''' – On a product page:
* '''Collection navigation example''' – On a product page:
<syntaxhighlight lang="liquid">
 
<pre>
{% if collection %}
{% if collection %}
   {% if collection.previous_product %}
   {% if collection.previous_product %}
Line 88: Line 92:
   {% endif %}
   {% endif %}
{% endif %}
{% endif %}
</syntaxhighlight>
</pre>
See [https://www.spiffystores.co.nz/kb/Liquid_Collection_Navigation Liquid Collection Navigation].
 
See [[Liquid Collection Navigation]].


* '''URL helper''' – Maintain collection context:
* '''URL helper''' – Maintain collection context:
<syntaxhighlight lang="liquid">
 
<pre>
{{ product.url | within: collection }}
{{ product.url | within: collection }}
</syntaxhighlight>
</pre>


=== Theme Settings ===
=== Theme Settings ===


Theme settings (colours, fonts, etc.) are configurable via the Toolbox and referenced in templates with <code>{{ settings.&lt;name&gt; }}</code>. See the [https://www.spiffystores.com.au/kb/ Knowledge Base] for details.
Theme settings (colours, fonts, etc.) are configurable via the Toolbox and referenced in templates with <code>{{ settings.&lt;name&gt; }}</code>.


== Assets, Scripts & Performance ==
== Assets, Scripts & Performance ==
Line 126: Line 132:
* Use <code>global_asset_url</code> helpers.
* Use <code>global_asset_url</code> helpers.
* Include SEO tags:
* Include SEO tags:
<syntaxhighlight lang="html">
 
<pre>
<meta name="description" content="{{ header.description }}">
<meta name="description" content="{{ header.description }}">
<meta name="keywords" content="{{ header.keywords }}">
<meta name="keywords" content="{{ header.keywords }}">
</syntaxhighlight>
</pre>
See [https://www.spiffystores.net.au/kb/Liquid_Template_Variables_-_header Liquid Template Variables – header].
 
* Maintain version control (e.g. Git) and backups.
* Maintain version control (e.g. Git) and backups.


Line 137: Line 144:
Add navigation to <code>product.liquid</code>:
Add navigation to <code>product.liquid</code>:


<syntaxhighlight lang="liquid">
<pre>
{% if collection %}
{% if collection %}
   <nav class="product-nav">
   <nav class="product-nav">
Line 148: Line 155:
   </nav>
   </nav>
{% endif %}
{% endif %}
</syntaxhighlight>
</pre>


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


== Migration & Update Considerations ==
== Migration & Update Considerations ==

Latest revision as of 07:52, 19 October 2025

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