# Sections

# Settings

There is a strict differentiation between "General settings" (styles) and Section settings.

# General Settings

General settings will be the one, which are involved into .css, .scss files. Our assets compilation process allows us to identify which setting correspond to which css rule and make the whole process of configuring them in Builder as smooth as possible. The whole approach and files structure for general settings remains the same:

Settings are provided to SCSS files using moustache syntax under 'settings' variable.
The schema is described inside "config/settings_schema.json" file with same rules, same settings types.
Presets go under folder "presets". There should be one file called "default.json" inside this folder.
Translations to schema go under "config/schema_translations" folder.

NB! The only change in settings schema is instead of "name_key" field let's use "handle". I realised that "handle" is more consistent with the project.

# Section Settings

Another type of settings belongs is Section Settings. Section settings are accessible from a section under variable 'section.settings'. Example:

{{ section.settings.header_text }}

The definition of section settings should be located inside section file using liquid tad "schema". More details see in the next chapter.

# Defining sections

Every section filename should begin with "_" (underscore). All section files should be located under "sections" directory.

Every section should contain only 1 root element (1 wrapping div). This root element should have the 'data-section-id' tag attached. This will simplify detecting sections in the Builder mode. Example:

<div data-section-id="{{ section.id }}">
 ... section data
</div>

Section settings should be described in separate .json files under "config/sections" directory. Example: for a section "_footer.liquid" should be a correspondent setting schema description inside the file "config/sections/footer.json"

{
  "name": "Footer",
  "generic": false,
  "settings": [
    {
      "type": "menu",
      "handle": "footer_menu1",
      "default": "footer"
    },
    {
      "type": "menu",
      "handle": "footer_menu2",
      "default": "header"
    },
    {
      "type": "checkbox",
      "handle": "show_powered_by",
      "default": true
    },
    {
      "type": "richtext",
      "handle": "description",
      "sidebar": false
    },
    {
      "type": "richtext",
      "handle": "description2",
      "sidebar": {
        "parent_node": {
          "handle": "show_powered_by"
          "values": [true]
        }
      } 
    }
  ]
}

As described above, every setting has its "handle". Section's "handle" is its filename (without underscore and extension). Example: handle of "_hero.liquid" is "hero". Handles are names of settings and they form altogether translation keys for settings.

Section setting definition may include parameter sidebar. It is used to calculate when to show setting in a sidebar. Parameter can be undefined or set to true/false/json. It's useful to have just false if you are working with richtext because user can see text editor and it's result on a page when he types. If you decide to use json then current main parameter is parent_node. Then it should have 2 keys: handle and values. Handle is string parameter which is same as parent setting handle. Values itself is an array of parent setting possible values. You may use it to show when toggle is only switched on or i.e. when select with different values or when user typed specific word.

A schema should define section as "generic", when it can be included to any page dynamically. Not every section should be allowed to be included dynamically to a page. Example: header (included already statically), product template (only included to the product page)

Available settings types are described in the table below:

Type	Description
text	Regular text field
richtext	HTML text
select	Select with options. Available options should be provided in the array "options"
number	Regular number field
checkbox	Regular boolean value
radio	Regular radiobutton functionality. "options" should be provided
range	Regular range field. Additional fields required: "min", "max", "step"
color	color picker (but color will be refreshed on iframe reload)
video	Video picker
collection	Will produce a combobox with collections
product	Will product a combobox with products
menu	Will produce a combobox with menus
image	Image picker.
blog_post	Combobox with blog posts
category	Combobox with categories
subcategory	Exists for structuring settings. Required "settings" field to be field with array for settings

Schema should also define default values for settings (if any) in the field "default":


{
  "name": "Footer",
  "generic": false,
  "settings": [
    {
      "type": "menu",
      "handle": "footer_menu1",
      "default": "footer"
    },
  ]
}

# Text setting tip

For the settings of type "text" (or richtext), please add additional data tag to the DOM element, like:

<p data-theme-editor-setting='title'> {{ section.settings.title }} </p>

(meaning the setting name), so in Builder mode it would be possible to identify the bearer of a setting and make the changing of it smooth and on-a-fly.

# Sections translations

NB: format changed

Sections translations (as well as translations of general settings) should go under "config/schema_translations/" folder in the following structure:

{
  "sections": {
    "section_handle": {
      "title": "My Section",
      "setting_handle": {
        "title": "Value",
        "options": { # optional, if e.g. select
          "bold": "Bold",
          "normal": "Normal"
        },
        "info": "Font weight of the main font" # optional
      }
    }
  },
  "general": {
      "css_setting_handle": {
         "title": "Main button color",
         "info": "Changes colors of the biggest buttons on the site" # optional
      }
  },
  "categories": {
    # as previously
  },
  "presets": {
    # as previously
  }
}

# Default values

Default values for settings are defined in several places, depending on a type of a setting:

All default values for a theme are located inside the file "config/settings_data.json". This file includes both default values for general settings (content of default preset), and default sections with their default values. For more information see next chapter.

# Settings data

In the config folder there should be a correspondent "settings_data.json" file. This file is describing current settings for all sections and current general settings, with which stylesheets are compiled. The format of this file is following:

{
  "general": { # here goes current general settings
     "body_bg_color": "#12345",
     ...
  },
  "sections": { # here we describe specific sections, which are already defined on some pages
      "header": { # key is an "id" of specific section, attached to a page. It can be any string
         "type": "header", # handle of section, derived from section file name
         "settings": { # here goes already specific section values
             "header": "Hello!",
             "image": 'https://cdn.site.com/image.png'
         },
         "translations": { # populated for settings of type 'text' or 'richtext' using Language tab in admin
            "et": {
               "header": "Tere!"
            },
            "en": {
               "header": "Hello!"
            }
         }
      },
      "hero-1": {
          "type": "hero",
          "settings": { ... }
      },
       "hero-2": {
          "type": "hero",
          "settings": { ... }
      }

  },
  "content_for_index": ["hero-1", "hero-2"] # set of sections (by their ID) in a correct order to include to an index page
}

# Including sections

Including a section is similar to including a fragment/partial (whatever we call it), but instead of "include" tag the "section" tag is used:

{% section 'header' %}

Section should be included by its ID. Including a section this way ensures that the section will receive the section object, from which it's possible to ask settings or "id", or maybe some other information.

# Buildable pages

When user open ThemeBuilder he should have a dropdown with pages, which he can customize. In order to define a page as 'customizable', you should include it to "customizable_pages" array inside the config/spec.json file. Example:

config/spec.json

{
  "handle": "universal",
  "name": "Universal",
  "author": "Shoperb",
  "year": "2016",
  "version": "0.8",
  "description": "Universal theme from Shoperb.com",
  "customizable_pages": ["index", "products", "product", "collection", "collections", "cart"]
  "compile": {
    ...
  }
}

# Page with dynamic sections

Currently index page will be the one, which will be including dynamic sections. In the index.liquid layout dynamic sections should be included with a following tag:


{{ content_for_template }}

← Liquid Drops Integrations →