# Basic Concepts

DEPRECIATION WARNING

We are phasing out support for previous generation themes, which can now only be deployed using Shoperb Theme Editor.

It is strongly recommended that you create themes supported by Theme Builder configuration (covered in this guide). Your clients will love you for that.

# Glossary

Here are some terms that will be used throughout this guide.

# Shoperb Theme Editor

This is a command line tool built as a Ruby gem form. Use $ shoperb --help in console to get you started on understanding Shoperb command line tool. After bundle installation, use $ shoperb init to initialize a new theme. This command will

# Theme Builder

Browser based user interface that allows our customers to create their own sites using sections based tool. Easy to use visual interface tool can be found on creation of ones' e-Commerce site on Shoperb platform. After signing up to Shoperb platform, Theme Builder is found on https://shoperb.app/ ready for the customer to add products and clients, vendors and collections etc.

# File Structure

Shoperb themes follow a rather strict folder and file structure. In the following example we are not including .shoperb file that will be created when you authenticate your project against a live Shoperb store and should not be committed into version control.

.
├── assets
|   ├── images
|   ├── javascripts
|   |   └── application.js
|   ├── fonts
|   └── stylesheets
|   |   └── application.css.scss
├── config
|   ├── schema_translations
|   |   ├── en-US.json
|   |   └── et-EE.json
|   ├── sections
|   |   ├── header.json
|   |   └── footer.json
|   ├── settings_data.json
|   ├── settings_schema.json
|   └── spec.json
├── emails - only if working with emails
|   └── customer.accepted.html.liquid
├── layouts
|   └── layout.liquid
├── presets
|   ├── preset-1.json
|   └── preset-2.json
├── sections
|   ├── my-section-1.liquid
|   └── my-section-2.liquid
├── templates
|   ├── index.liquid
|   ├── cart.liquid
|   └── page.liquid
├── translations
|   ├── en.json
|   └── et.json
└── CHANGELOG.md

# Template markup language

For creating theme for Shoperb stores we use markup language Liquid, developed by Shopify. You can check out Liquid documentation by the following link: Liquid documentation (opens new window).

Every liquid template of the theme is supplied with a bunch of variables, which will be discussed in next chapters.

# Assets

Assets in Shoperb themes are heavily inspired by how assets are managed in Ruby on Rails.

Two manifest files — application.js and application.css.scss — are used to include all other relevant JavaScript and CSS/SCSS files. It is recommended that you use these files to include your assets in these files as it makes your life deploying a theme much easier.

# JavaScripts

JavaScripts manifest is located at /assets/javascripts/application.js

We recommend serving only 1 javascript file on the page for the sake of speed of page load. However, for development purposes you are always free to break it down into several files. In the result 'application.js' file you can simply use 'require' directives, which are described below, for including content of other files.

In the example below require includes the content of specified file into current one and require_tree includes content of all files in a specified directory to the current file.

//= require jquery
//= require path/to/other_file
//= require_tree path/to/whole/directory
//= require_tree .

# Stylesheets

Stylesheets manifest is located at /assets/stylesheets/application.css.scss

We use SCSS variables throughout our themes to allow easy customization in Theme Builder.

In the example below require_self simply includes content of current file. With this function you can define the order of included content.

*= require nouislider
*= require jquery-ui
*= require relative/path/to/any/other/css
*= require jquery-ui/datepicker
*= require_self

# Config

# spec.json

Located in config/spec.json we use this file to define meta data of the theme, like: author, year, name, handle, description. Some values in this file are obligatory:

# spec.json

{
  "handle": "canvas",
  "name": "Canvas",
  "author": "Shoperb",
  "year": "2017",
  "version": "1.0.0",
  "description": "Canvas is a skeleton theme that can be used to start building custom Shoperb themes.",
  "customizable_pages": [
    "index"
  ],
  "compile": {
    "stylesheets": [
      "application.css"
    ],
    "javascripts": [
      "application.js"
    ]
  }
}

Key	Description
handle	Theme handle must be a unique value on Shoperb platform. For example, there can be only one theme that has an handle canvas on Shoperb.
name	Theme name is a pretty display name for your theme.
description	Short description for your theme.
author	Your or your company name. This will be displayed in Shoperb Theme Store as who created this theme.
year	Year when the theme was initially created.
version	We use semantic versions pattern here.
customizable_pages	Template names that can be customized with Theme Builder.
compile	List of stylesheets and javascript assets that should be served directly on every page.

# settings_schema.json

Located in config/settings_schema.json this file is used to describe general options for the theme. This would include settings like colors, font family, font size, favicon, etc that would apply for the whole theme. You can think of it as of description of settings that apply for the whole theme layout.

List of available settings is described in the table below:

Key	Format in the Theme Builder	Options
color	Color picker	"default" value
select	Select dropdown	"options" array with options: `{handle: "my-setting-name", value: "my-setting-value"}` "default" value
number	Number field	"min", "max", "default"
text	Text field	"default"
font	Select dropdown with font names	"options" array with options: `{ handle: "my-font-setting-name", value: "my-font-value" }` "default" value
image	Image picker	"default" value
toggle	Toggle switcher	"default" value. Accepts true/false values

# settings_data.json

Located in config/settings_data.json this file is used for defining actual settings values for the theme. The moment, when end-user will install the theme to the store, these settings will be applied as default settings. settings_data.json file defined general styling settings as well as section settings, which will be discussed in Chapter 'Sections'.

Example of file:

{
  "general": {
    "text_headings_color": "#1B2026",
    "text_body_color": "#A2A4A8",
    "text_sale_text_color": "#1B2026",
    "text_link_color": "#1B2026",
    "heading_scaling": "1.25",
    "square_images": false
  },
  "sections": {
    "hero-1": {
      "type": "image_with_text_overlay",
      "settings": {
        "image_alignment": "center",
        "title": "Large image with text",
        "text": "This area here is good getting the attention of your customers.",
        "text_size": "medium",
        "section_height": "medium",
        "section_width": "limited",
        "button_label": "Click here!",
        "button_link": ""
      },
      "id": "hero-1"
    }
  },
  "content_for_index": [
    "hero-1"
  ]
}

# Layouts

Shoperb provides set of snippets, which should be used within the theme. These snippets are described in the table below:

# shoperb_header

Used to include any scripts (integrations) that should go in between <head> and </head> tags.

Auto-includes selected plugins (inside the body)

# shoperb_stylesheets

Includes stylesheets (goes into head)

NB! Stylesheets (with settings!) MUST be included excusively using snippet shoperb_stylesheets. (Small explanation why: because they are included in a different way for a regular view and preview mode. And this snippet handles it the way it should be handled. )

<html>
  <head>
    {% include 'shoperb_stylesheets', stylesheets: 'application.css' | split: '|' %}
    {% include 'shoperb_header' %}
  </head>

  <body>
     {% include 'shoperb_footer' %}
  </body>
</html>

# Templates

Every theme should define the following set of templates:

Page	Description
index.liquid	Store main page
login.liquid	Login page
signup.liquid	Registration page
account.liquid	User account page
billing_payment_method	User credit card show page
billing_payment_methods	Page of user credit card collections
billing_subscription	Page to show/edit user subscription
billing_subscription_plans	Page of all subscription plans
billing_subscriptions	Page of user subscription collections
blog_post.liquid	Blog post page
blog_posts.liquid	Blog page
cart.liquid	User cart page
order.liquid	User order page
orders.liquid	Page of all user orders
product.liquid	Product page
products.liquid	Page of all store products
category.liquid	Product category page
collection.liquid	Product collection page
collections.liquid	Page of all product collections
page.liquid	Store custom page template
password_change.liquid	Password change page - url is `/language/reset`, e.g. `/en/reset`
password_request.liquid	Password change request page
passwrord_token_sent.liquid	Password change request sent page
reviews.liquid	Product reviews page
search.liquid	Search page
not_found.liquid	"Not found (404)" page

As you can see, every template defined every page of store, that store can have. Check out examples of templates of our skeleton theme "Canvas" here: Canvas templates (opens new window)

Templates can name names with or without an underscore in the beginning. According to Liquid naming conventions, the template with an underscore in the beginning is a "partial" of a template, meaning, it is a reusable part of template, which can be included into other templates.

Partials are files containing chunks of reusable code.
They name start with underscore.
They have the .liquid extension.
They are most often used for code that appears on more than one page but not across the entire theme.
Partials are included in a template using the Liquid tag include e.g. {% include ‘snippet name’ %}.
You do not need to append the .liquid extension when referencing the partial name.
When a partial is included it will have access to the variables within its parent template.

Partials are extremely useful and allow you to keep repeated code in a single file.

Example:

{% for product in paginate.collection %}
  {% include 'product' with 'page' %}
{% endfor %}
</div>
{% include 'pagination' %}

# Translations

'Translations' folder includes all translations of your theme to languages, which it supports.

Locale files have .json extension
Locale files are named with locale name
Locale file content is a json with a single root of self-titled locale.

Example:

# en.json

{
  "en":
    {
      "product.unavailable": "Product is currently unavailable",
      "product.unavailable_short": "Currently unavailable",
      "product.quantity": "Quantity",
      "product.add_to_cart": "Add to Cart",
      "product.recommended": "You might also like",
      "product.sku": "SKU",
      "product.select": "Select",
      "product.compare_at": "Market price"
    }
  }
}

In the same manner you can define files fr.json, et.json, ru.json or any other language you want to support.

Having translations defined this way allows you to access the correspondent string in your template in the following way:

{{'product.recommended' | t}}

Where t is an alias for translate filter of Liquid. You can read more about Liquid filters here.

# Presets

Presets files store possible values for styling settings. Presets files are not obligatory in the folder, however, they can improve end-user experience of theme customizing a lot.

Upon creating a theme you can define a preset "Dark", which would contain a set of settings values, which would create beautifl dark-colored version of your theme. In addition, you could create a preset "Art", where you could put a set a settings values, which would make your theme look artistics and colorful, and so on. Such presets of settings could give to end-user a broader overview of how it is possible to customize the theme.

Presets should be stored in the folder /presets.

The example of the preset file:

{
  "handle": "dark",
  "default": false,
  "settings": {
    "text_headings_color": "#FFFFFF",
    "text_body_color": "#D9D9D9",
    "text_sale_text_color": "#D6A356",
    "text_link_color": "#FFFFFF",
    "buttons_primary_button_background_color": "#EF5948",
    "layout_background_color": "#0D0909",
    "layout_border_color": "#CED3D9",
    "layout_secondary_background_color": "#262322",
    "layout_header_footer_background_color": "#0D0909",
    "image_overlay_color": "#FFFFFF",
    "image_overlay_background": "#262322",
    "image_overlay_opacity": "0.6",
    "body_font_family": "Open Sans",
    "heading_font_family": "Hind",
  }
}

# Sections

Shoperb themes have a folder sections, which contains reusable fragments of templates, which end-user can assemble together and build a page in the Theme Builder.

Sections have .liquid extension
Sections can be generic (dynamic) or not generic (static). Generic sections (dynamic) can be added to any page. Not generic sections (also can be called 'static') cannot be added or removed by end-user. However, they are an integral part of a template. Example: header, footer.

# Static (or non-generic sections)

Static sections are included to template or layout with a section tag:

{% section 'header' %}

End-user will see this section in Theme Builder and will be able to custmize it. However, user won't be able to add one more header or remove an existing one.

# Dynamic sections

Dynamic sections can be added to the template using tag content_for_template:

{% content_for_template %}

More about sections read in a Chapter "Sections".

# Changelog

← Getting Started Liquid Tags →

# Basic Concepts

# Glossary

# Shoperb Theme Editor

# Theme Builder

# File Structure

# Template markup language

# Assets

# JavaScripts

# Stylesheets

# Config

# spec.json

# spec.json

# settings_schema.json

# settings_data.json

# Layouts

# shoperb_header

# shoperb_footer

# shoperb_stylesheets

# Templates

# Translations

# en.json

# Presets

# Sections

# Static (or non-generic sections)

# Dynamic sections

# Changelog