Selenic Systems

Getting started

Catalogue turns your product data into an offline catalogue and ordering tool for Android. This guide walks through the three things that make it work: your product data, your templates, and the build that packages them for the app.

How Catalogue fits together

Catalogue is driven entirely by files you control:

  • Product data — the source of truth for your range, supplied as JSON, XML or CSV.
  • Templates — Liquid files that decide how products are laid out, grouped and displayed.
  • Assets — product images and any static files referenced by your templates.

When you build a catalogue, these are compiled into a single package that installs on the device. From then on, everything works fully offline — no connection is needed to browse the range or take an order.

Before you begin

You will need:

  • The Catalogue admin tools (supplied with your licence).
  • Your product data in one of the supported formats.
  • A folder of product images, if you use them.

1. Create a project

A project is a folder with a predictable shape. Create one like this:

Shell
catalogue init my-catalogue
cd my-catalogue

This produces the following structure:

Text
my-catalogue/
├── catalogue.config.json   # project settings
├── data/                   # your product data (JSON, XML or CSV)
│   └── products.json
├── templates/              # Liquid templates
│   ├── index.liquid
│   └── product.liquid
└── assets/
    └── images/             # product images

2. Add your product data

Drop your product file into data/. The smallest valid product needs an id, a title and a price:

JSON
{
  "products": [
    {
      "id": "sku-1001",
      "title": "Field Notebook A5",
      "price": 8.5,
      "currency": "GBP",
      "in_stock": true
    }
  ]
}

The full set of fields, and how to load XML and CSV instead, is covered in Importing product data.

3. Point the config at your data

catalogue.config.json tells the build where to find things:

JSON
{
  "name": "My Catalogue",
  "data": "data/products.json",
  "templates": "templates",
  "assets": "assets",
  "currency": "GBP",
  "currencySymbol": "£"
}

4. Lay out a product

Templates are written in Liquid. A minimal templates/product.liquid might read:

Liquid
<article class="product">
  <h1>{{ product.title }}</h1>
  <p class="price">{{ product.price | money }}</p>

  {% if product.in_stock %}
    <p class="stock in">In stock</p>
  {% else %}
    <p class="stock out">Out of stock</p>
  {% endif %}

  <p>{{ product.description }}</p>
</article>

The Liquid templating guide explains every object, filter and tag available to you, with copy-and-paste recipes.

5. Build the catalogue

Compile the project into an installable package:

Shell
catalogue build

The build validates your data against the schema, renders your templates, and writes a package to dist/. If anything is wrong with your data or templates, the build stops and tells you exactly where — see Troubleshooting if you get stuck.

6. Preview on a device

Install the package on an Android device with the Catalogue app, or use the built-in preview:

Shell
catalogue preview

Preview serves the catalogue exactly as it will appear in the app, so you can check layout and content before you distribute it to your team.

Next steps