Limited Run - Commerce & Newsletters for Labels, Musicians, and Artists

Have a question about your order? Please contact the store you ordered from directly.
You can do this by replying to your order confirmation email.

Anatomy of a Theme

If you have any questions, please send us a message.

Every Theme is made up of many Assets and each Asset is one of many types:

layout
stylesheet
javascript
template
snippet
config

layouts

Every Theme must have a default.html layout. A layout contains the main structure of your site and store. This includes things like your html, head and body tags.

An example of a layout is:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>{{ store.name }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

Note that {{ content }} is where the template gets rendered within the layout.

stylesheets

Every Theme must have a default.css stylesheet. A stylesheet contains a Theme's css.

A stylesheet can be rendered like:

{{ 'default.css' | asset_url | stylesheet_tag: 'screen' }}

Which would produce a custom link tag like:

<link href="/asset/default-c6324.css" media="screen" rel="stylesheet" type="text/css"/>

javascripts

Every Theme must have a default.js javascript. A javascript contains a Theme's javascript.

A javascript can be rendered like:

{{ 'default.js' | asset_url | script_tag }}

Which would produce a custom script tag like:

<script src="/asset/default-39e50.js" type="text/javascript"></script>

templates

Every Theme has many templates. A template is rendered within a layout and usually lines up with a specific page. For example, the product.html template is rendered on product pages.

Default templates include:

index.html
category.html
product.html
order.html
maintenance.html
404.html

There are also specialty templates for Apps, including:

news.html
news-item.html
history.html
gallery.html
contact.html

snippets

Snippets are optional and can be used to repeat blocks of a template from multiple areas.

An example is a sidebar.html snippet that is rendered within some, but not all, templates.

A snippet is rendered with include, like a {% tag %}, such as:

{% include 'sidebar.html' %}

configs

Every Theme must have a default.json config. A config is a json formatted document and includes Theme details such as the author, images for the Theme Gallery as well as setting definitions.

An example of a default.json config is as follows:

{
  "name": "Classic",
  "description": "The classic theme for Limited Run.",
  "author": {
    "name": "Limited Run",
    "website": "http://limitedrun.com"
  },
  "images": [
    {
      "thumbnail": "http://.../classic-1-thumb.png",
      "original": "http:/.../classic-1.png"
    },
    {
      "thumbnail": "http://.../classic-2-thumb.png",
      "original": "http://.../classic-2.png"
    }
  ],
  "settings": {
    "background_image_url": {
      "format": "image",
      "label": "Background Image URL",
      "help": "Enter an image URL or choose an image file to upload.",
      "placeholder": "http://",
      "position": 0
    },
    …
  }
}

Every default.json config can have many settings. Each setting requires the following things:

key - ex: "background_image_url"
format - Possible values include: "image", "color", "text", "boolean"
label - ex: "Background Image URL"
position - ex: 0, 1, 2, 3, etc.

Optional fields include:

default - a default value, such as #E5E5E5 for a color or true for a boolean
help - a further explanation
placeholder - an example value

All of the settings in a Theme are show in the "Options" area in the Storefront > Theme area of the Dashboard.

Each format shows a different input field in the "Options" area. The "color" format shows a color picker. The "image" format shows a text field (for an image url) with an adjacent "Upload Image" button. The "text" format shows a plain text field. The "boolean" format shows a checkbox.

To use an option's value in your theme, whether in your default.html, or your default.css, or any other theme asset, simply reference its key, like {{ config['background_image_url'] }}.

Help