Theme Domain Specific Language

Chocobrain's Theme Domain Specific Language (TDSL) allows Theme designers to configure input fields inside the Templates of section, website or page. Using these fields Content managers provide the content to be rendered by the SectionTemplate and are able to make design adjustments Theme designers see fit.

Moreover Theme designers can configure presets to provide default content right on creation of website, page or section. By defining Page Generators on PageTemplates Theme designers can even define which sections to be created on page creation. Independent definition of presets and generators allows Content managers to select any combination of them.

Define with schema

Each SectionTemplate must contain a schema, which needs to be valid JSON put into the slot of a Liquid tag schema and needs to adhere to following API.

Minimum required fields of schema block depend on the context: schema_name needs to be provided always, but css_class and tag can only be provided on SectionTemplates.

• Required content on SectionTemplate:

  {% schema %}
      {
          "schema_name": "my_schema_name",
          "css_class": "my_classes",
          "tag": "div"
      }
  {% endschema %}

  • Required content on website:

  {% schema %}
      {
          "schema_name": "website"
      }
  {% endschema %}

schema_name

• Type: string
• Allowed characters: A-Za-z0-9_
• Description: Name must be unique amongst all SectionTemplates.
• Typical Usage:

  "schema_name": "my_schema_name"

css_class

• Type: string
• Allowed characters: A-Za-z0-9-
• Description: Class content must be unique amongst all SectionTemplates.
• Typical Usage:

  "css_class": "my_classes"

tag

• Type: string
• Allowed values:
  • div
  • section
  • article
  • aside
  • footer
  • header
• Description: Rendered HTML of a section is wrapped by this HTML tag with class attribute containing the classes given via css_class field.
• Typical Usage:

  "tag": "div"

settings

• Type: array of objects
• Description: Settings array inside the schema JSON consists of Setting objects, where each configures one field in the EditorSidebar inside the chocoBRAIN4-App.

blocks

• Type: array of objects
• Description: The blocks array inside the schema JSON consists of Block objects, where each configures one field in the EditorSidebar inside the chocoBRAIN4-App.

presets

• Type: array of objects
• Description: The presets array inside the schema JSON consists of Preset objects, where each configures one set of field presets and can be used to provide a url to a preview image. Beyond that a settings array can be provided with preset content which fills input fields on a section's creation.

Setting

Each setting object has at least three fields: name, label and kind.

• Typical usage: e.g. configuring a text field

  {% schema %}
  {
      "schema_name": "my_schema_name",
      "css_class": "my_classes",
      "tag": "div",
      "settings": [
          {
              "name": "my_schema_setting_name",
              "label": "my_schema_setting_label",
              "kind": "text"
          }
      ]
  }
  {% endschema %}

name

• Type: string
• Allowed characters: A-Za-z0-9
• Description: The name must be unique amongst all schema settings of one SectionTemplates. It is use only internally to allocate inputs correctly despite change of the externally used label in the EditorSidebar.
• Typical Usage:

  "settings": [
      {
          "name": "my_schema_setting_name",
          ...
      }
  ]

label

• Type: string
• Allowed characters: A-Za-z0-9+-; and single white-space inside
• Description: The label must be unique amongst all schema settings of one SectionTemplate. It is use used extern in the EditorSidebar and can be adjusted without deleting already made inputs by Content managers in specific sections.
• Typical Usage:

  "settings": [
      {
          "label": "my_schema_setting_label",
          ...
      }
  ]

kind

• Type: string
• Allowed values:
  • for primitive values: text, textarea, date, range, number, select, faq_item_tag_name
  • for object references: rich_text, color, link, link_list, form, image
• Description: Depending on the kind further fields must be configured.
• Typical Usage:

  "settings": [
      {
          "kind": "text",
          ...
      }
  ]

text

• Allowed input values: UTF-8 characters without line breaks.
• For usage see text.
• Typical content:

  {
      "name": "my_text_name",
      "label": "my text label",
      "kind": "text"
  }

textarea

• Allowed input values: UTF-8 characters with line breaks.
• For usage see textarea.
• Typical content:

  {
      "name": "my_textarea_name",
      "label": "my textarea label",
      "kind": "textarea"
  }

rich_text

• Allowed input values: UTF-8 characters with line breaks and restricted formatting.
• For usage see richtext object.
• Typical content:

  {
      "name": "my_richtext_name",
      "label": "my richtext label",
      "kind": "rich_text"
  }

date

• Allowed input values: A DOMString representing a date in YYYY-MM-DD format, or empty.
• For usage see date.
• Typical content:

  {
      "name": "my_date_name",
      "label": "my date label",
      "kind": "date"
  }

color

• Allowed input values: Only selectable colors are those, that were created and named via the chocobrain Color Picker. Transparency is not included.
• For usage see color object.
• Typical content:

  {
      "name": "my_color_name",
      "label": "my color label",
      "kind": "color"
  }

range

• Allowed input values: Numbers inside a given range only. The given step makes it impossible to choose other values and the allowed values are validated. The max value must be reachable by a multiple in whole numbers of step starting from the min value.
• Additional required setting fields: min, max and step.
• For usage see range.
• Typical content:

  {
      "name": "my_range_name",
      "label": "my range label",
      "kind": "range",
      "min": 0,
      "max": 1200,
      "step": 10
  }

number

• Allowed input values: Numbers inside a given range only. The given step is only for input convenience and is not validated.
• Additional required setting fields: min, max and step.
• For usage see number.
• Typical content:

  {
      "name": "my_number_name",
      "label": "my number label",
      "kind": "number",
      "min": 0,
      "max": 1000,
      "step": 10
  }

link

• Allowed input values: link object
• For usage see link object.
• Typical content:

  {
      "name": "my_link_name",
      "label": "my link label",
      "kind": "link"
  }

link_list

• Allowed input values: link_list object
• For usage see link_list object
• Typical content:

  {
      "name": "my_link_list_name",
      "label": "my link_list label",
      "kind": "link_list"
  }

form

• Allowed input values: form object
• For usage see form object
• Typical content:

  {
      "name": "my_form_name",
      "label": "my form label",
      "kind": "form"
  }

image

• Allowed input values: image object
• For usage see image object
• Typical content:

  {
      "name": "my_image_name",
      "label": "my image label",
      "kind": "image"
  }

select

• Possible input values: the given option values and nil for no user input
• Additional required setting fields: options, which is an array of objects, where each option object requires three fields: name, label, value. For further information see options.
• For usage see select
• Typical content:

  {
      "name": "my_select_name",
      "label": "my select label",
      "kind": "select",
      "options": [
          {
              "name": "my_select_name_option_1",
              "label": "my select name option 1",
              "value": "option_1"
          },
          {
              "name": "my_select_name_option_2",
              "label": "my select name option 2",
              "value": "option_2"
          }
      ]
  }

faq_item_tag_name

• Possible input values: system generated select field for all tags on Faq items.
• For usage see faq_item_tag_name
• Typical content:

  {
      "name": "my_faq_item_tag_name_name",
      "label": "my faq_item_tag_name label",
      "kind": "faq_item_tag_name"
  }

min

• Allowed values: Positive numbers, smaller than max value.
• The setting objects range and number require it. The max value must be reachable by a multiple in whole numbers of step starting from the min value.
• Typical content:

  {
      ...
      "min": 0,
      ...
  }

max

• Allowed values: Positive numbers, greater than min value.
• The setting objects range and number require it. The max value must be reachable by a multiple in whole numbers of step starting from the min value.
• Typical content:

  {
      ...
      "max": 100,
      ...
  }

step

• Allowed values: Positive numbers.
• The setting objects range and number require it. The max value must be reachable by a multiple in whole numbers of step starting from the min value.
• Typical content:

  {
      ...
      "step": 5
  }

options

• Type: array of objects
• Description: Options array inside a setting of kind select consists of option objects, where each configures one row in the dropdown select-field in the EditorSidebar inside the chocoBRAIN4-App.

option

• Required fields: name, label and value.
• The setting object select requires an array of options.
• Typical content:

  {
      "name": "my_select_name",
      "label": "my select label",
      "kind": "select",
      "options": [
          {
              "name": "my_select_name_option_1",
              "label": "my select name option 1",
              "value": "option_1"
          },
          ...
      ]
  }

name

• Allowed characters: A-Za-z0-9
• Typical content:

      {
          "name": "my_select_name_option_1",
          ...
      }

label

• Allowed characters: A-Za-z0-9:,-_()% and space
• Typical content:

      {
          "label": "my select label (option 1)",
          ...
      }

value

• Allowed characters: A-Za-z0-9 and space
• Typical content:

      {
          "value": "option-1",
          ...
      }

Block

• Type: object
• Description: Each block consists of one or more Setting objects and the Content Manager can add multiple instances of them, only confined by the given limit.
• Required fields: name, label, limit, and settings
• Typical usage: e.g. configuring a block with an image and a headline

  {% schema %}
      {
          ...
          "blocks": [
              {
                  "name": "slider_slides",
                  "label": "Slides",
                  "limit": 20,
                  "settings": [
                      {
                          "name": "slide_image",
                          "label": "Bild",
                          "kind": "image"
                      },
                      {
                          "name": "slide_headline",
                          "label": "Überschrift",
                          "kind": "text"
                      }
                  ]
              }
          ]
      }
  {% endschema %}

name

• Type: string
• Allowed characters: A-Za-z0-9
• Description: Name must be unique amongst all block settings of one blocks array. It is used only internally to allocate inputs correctly despite change of the externally used label in the App's EditorSidebar.
• Typical Usage:

  "blocks": [
      {
          "name": "my_schema_setting_name",
          ...
      }
  ]

label

• Type: string
• Allowed characters: A-Za-z0-9+-; and single white-space inside
• Description: label must be unique amongst all block settings of one blocks array. It is use used extern in the App's EditorSidebar and can be adjusted without deleting already made inputs by Content managers in specific sections.
• Typical Usage:

  "blocks": [
      {
          ...
          "label": "my_schema_setting_label",
          ...
      }
  ]

limit

• Type: number
• Allowed range: 1+
• Description: limit is used to limit the maximum number of this Block that a Content Manager can create.
• Typical Usage:

  "blocks": [
      {
          ...
          "limit": 5,
          ...
      }
  ]

settings

• Type: array of objects
• Description: The settings array inside the schema JSON consists of Setting objects, of which each configures one field in the EditorSidebar inside the chocoBRAIN4-App.
• Typical Usage:

  "blocks": [
      {
          ...
          "settings": [
              {
                  "name": "slide_image",
                  "label": "Bild",
                  "kind": "image"
              },
              ...
          ]
      }
  ]

Usage of settings

Use section.settings.MY_TDSL_NAME to reach content of TDSL-field of section or section.dynamic_blocks.MY_BLOCK_NAME[i].settings.MY_TDSL_NAME to reach content of TDSL-field of block. Except for the TDSL-fields text, textarea, number, range and select the corresponding object is returned.

Settings

text

• Type: string
• Description: Contains the text string inserted into the corresponding TDSL-field in section, which is nil when the field is empty.
• Typical Usage:
  • Use for section heading, e.g. when setting name is my_section_heading.

  {%- if section.settings.my_section_heading -%}
      <h2>
          {{section.settings.my_section_heading}}
      </h2>
  {%- endif -%}

textarea

• Type: string
• Description: Contains the textarea string inserted into the corresponding TDSL-field in section, which is nil when the field is empty and may contain \n as line breaks which must be replaced by <br> in HTML by Liquid filter newline_to_br.
• Typical Usage:
  • Use for multiline texts without formatting, e.g. a textarea named my_textarea.

      <p>
          {{section.settings.my_textrea | newline_to_br}}
      </p>

number

• Type: number
• Description: Contains the number inserted into the corresponding TDSL-field in section, which is nil when the field is empty. The number must be an integer.
• Typical Usage:
  • Use for input that needs to be a number, e.g. a number named my_padding_in_px.

  <div style="padding: {{section.settings.my_padding_in_px}}px;">
      ...
  </div>

range

• Type: range
• Description: Contains the number selected via range field of corresponding TDSL-field in section, which is nil when the field has never been used. Main difference to a number field is the draggable button to determine its value in Editor sidebar and that it cannot be reset to its original value nil by Content managers. A reset or delete results in the lowest possible value as inserted into the min value field.
• Typical Usage:
  • Use for input that needs to be a number, e.g. a number named my_margin_in_px.

  <div style="margin: {{section.settings.my_margin_in_px}}px;">
      ...
  </div>

select

• Type: string
• Description: Contains the value string of the corresponding select option of the TDSL-field in section, which is nil when no option was selected.
• Typical Usage:
  • Use for input that needs to be one of several values, e.g. a specific class for the select field named margin_size_class.

  <div class="{{margin_size_class}}">
      ...
  </div>

date

• Type: string

• Description: Contains the a string representing the date in the format YYYY-MM-DD or is nil when field is empty. the string can be reformatted using Liquid filter date.

• Typical Usage:

  • Use for input that needs to be a date, e.g. a date field named my_date.

  <p>
      {{my_date | date: "%e.%m.%Y"}}
  </p>

faq_item_tag_name

• Type: array of objects
• Description: Contains array of all faq item objects with selected tag.
• Typical Usage:
  • Use to show only a subset of faq_items on a special topic.

  {%- for faq_item in section.settings.my_faq_item_tag_name_name -%}
    <div>
      <p>
        {{ faq_item.question_plain }}
      </p>
      {{ faq_item.answer_html }}
    </div>
  {% endif %}

rich_text

See richtext object

image

See image object

link

See link object.

link_list

See link_list object.

color

See color object

form

See form object

dynamic_blocks

• Type: list of arrays
• Description: Contains a list of arrays of content blocks added by Content managers on basis of a dynamic_block defined by the Theme designer. A specific array of content blocks is called by section.dynamic_blocks.MY_BLOCK_NAME and contains a Setting object with all settings of the block as defined by the Theme designer and inserted by Content managers.
• Typical Usage:
  • Use for gallery of images, e.g. when block name is my_gallery_block and setting name is my_gallery_image.

  {% for dynamic_content_block in section.dynamic_blocks.MY_GALLERY_BLOCK %}
    {% assign my_image_object = dynamic_content_block.settings.MY_GALLERY_IMAGE %}
    ...
  {% endfor %}

Preset

Each preset object has at least three fields: name, label and preview_image_url. Optionally a settings array can be provided with preset content which fills input fields on a section's creation. In similar fashion a blocks array can be which creates blocks with their own settings on a section's creation. For object fields a set of preset objects are provided to choose from.

• Typical usage: making a preview image available and defining preset contents in preset's settings array

  {% schema %}
  {
    "schema_name": "my_schema_name",
    "css_class": "my_classes",
    "tag": "div",
    "settings": [ ... ],
    "blocks": [ ... ],
    "presets": [
      {
        "name": "my_schema_preset_name",
        "label": "my_schema_preset_label",
        "preview_image_url": "https://www.mypics.de/my_image.jpg",
        "settings": [ 
          {
            "name":"text_setting_name",
            "default":"Beliebiger Inhalt eines primitiven Textfeldes."
          },
          {
            "name":"image_setting_name",
            "default":"logo_4by3"
          }
        ],
        "blocks": [ 
          {
            "name":"block_type_name1",
            "settings": [ 
              {
                "name":"other_text_setting_name",
                "default":"Beliebiger Inhalt eines primitiven Textfeldes."
              }
            ]
          },
          {
            "name":"block_type_name1"
          },
          {
            "name":"block_type_name2",
            "settings": [ 
              {
                "name":"other_image_setting_name",
                "default":"logo_4by3"
              }
            ]
          }
        ]
      }
    ]
  }
  {% endschema %}

name

• Type: string
• Allowed characters: A-Za-z0-9
• Description: The name must be unique amongst all presets of one SectionTemplate. It is used only internally to allocate inputs correctly despite changes of the externally used label and preview_image_url in the EditorSidebar.
• Typical Usage:

  "presets": [
      {
          "name": "my_preset_name",
          ...
      }
  ]

label

• Type: string
• Allowed characters: A-Za-z0-9+-; and single white-space inside
• Description: The label must be unique amongst all presets of one SectionTemplate. It is use used externaly in the EditorSidebar and can be changed anytime.
• Typical Usage:

  "presets": [
      {
          "label": "my_preset_label",
          ...
      }
  ]

preview_image_url

• Type: url
• Description: Url must link to an available image.
• Typical Usage:

  "presets": [
      {
          "preview_image_url": "https://www.mypics.de/my_image.jpg",
          ...
      }
  ]

settings (presets)

• Type: array of objects
• Description: Preset settings array inside presets of schema JSON consists of preset setting objects, where each fills one setting field.
• Typical Usage:

  "presets": [
      {
          ...
              "settings": [ 
                {
                    "name":"text_setting_name",
                    "default":"Beliebiger Inhalt eines primitiven Textfeldes."
                },
                                {
                    "name":"image_setting_name",
                    "default":"logo_4by3"
                },
                ...
              ]
          ...
      }
  ]

setting (preset)

Each preset setting object has name and default field.

• Typical Usage:

  "presets": [
      {
          ...
              "settings": [ 
                {
                    "name":"text_setting_name",
                    "default":"Beliebiger Inhalt eines primitiven Textfeldes."
                },
                ...
              ]
          ...
      }
  ]

name (preset)

Name must correspond with name of a defined setting.

default

Default value can either be arbitrary values for primitive fields, e.g. text or number, or a set of predefined preset object names, e.g. link or image. For a comprehensive list of available kinds see setting's kind.

Predefined constant objects for usage

These preset objects are only available through presets and its content cannot change. They represent dummy content which is important to show the typical Layout and Design of sections, pages and websites, but is not thought of to be of any use on published websites.

• faq_items with faq_item_tag_names:
  • Preset-Tag1
  • Preset-Tag2
  • Preset-Tag3
• image:
  • general_5by1
  • general_3by1
  • general_16by9
  • general_1by1
  • general_9by16
  • person_16by9
  • person_1by1
  • person_9by16
  • logo_16by9
  • logo_1by1
  • logo_9by16
• rich_text:
  • lorem_xsmall
  • lorem_small
  • lorem_medium
  • lorem_large
  • lorem_xlarge
  • list_small
  • list_medium
  • list_large
  • lorem_with_headings_small
  • lorem_with_headings_medium
  • lorem_with_headings_large
• links:
  • intern_small
  • extern_medium
• link_lists:
  • level1_small
  • level1_large
  • level2_small
  • level2_large
  • level3_small
  • level3_large

Predefined modifiable objects for usage

These preset objects are not only available through presets but also for Content managers, which can even change their content. They represent prebuilt content which is thought to be valuable as such on websites, at least partly.

• color:
  • primary
  • primary_hover
  • secondary
  • secondary_hover
  • black
  • white
  • gray_light
  • gray_medium
  • gray_dark
• forms:
  • general_medium
  • download_small
  • download_large
  • recruiting_small
  • recruiting_large

blocks (presets)

• Type: array of objects
• Description: Preset blocks array inside presets of schema JSON consists of preset blocks objects, where each is used to create one block. Each block has its own settings, which are filled by values given by a settings array inside the preset block. Name of preset block has to be one of the defined schema block.
• Typical Usage:

  "presets": [
    {
      ...
        "blocks": [ 
          {
            "name":"block_type_name1",
            "settings": [ 
              {
                "name":"text_setting_name",
                "default":"Beliebiger Inhalt eines primitiven Textfeldes."
              },
              {
                "name":"image_setting_name",
                "default":"logo_4by3"
              },
              ...
            ]
          },
          {
            "name":"block_type_name1",
            "settings": [ 
              {
                "name":"text_setting_name",
                "default":"Andere Inhalt"
              },
              {
                "name":"image_setting_name",
                "default":"logo_1by1"
              },
              ...
            ]
          }
        ]
      ...
    }
  ]

block (preset)

Each preset block object has name and settings fields. Preset block settings

• Typical Usage:

  "presets": [
      {
          ...
            "blocks": [ 
              {
                "name": "block_type_name1",
                "settings": [ 
                  {
                    "name":"text_setting_name",
                    "default":"Beliebiger Inhalt eines primitiven Textfeldes."
                  },
                  {
                    "name":"image_setting_name",
                    "default":"logo_4by3"
                  },
                  ...
                ]
              }
              ...
            ]
          ...
      }
  ]

name (preset-block)

Name of preset block has to be one of defined schema blocks.

settings (preset-block)

Settings array contains fields which have to correspond to names of defined block settings. Apart from this they need to adhere to same rules as other preset settings.

Page Generator

Each page generator object has three fields: name, label and sections and can be added to PageTemplates. On page creation users can select one generator, which determines which page sections are created inside the newly created page.

• Typical usage: Create several sections on page creation.

{% schema %}
{
  "schema_name": "my_schema_name",
  "css_class": "my_classes",
  ...
  "generators": [
    {
      "name": "my_generator_name",
      "label": "my generator label",
      "sections": [ 
        {
          "template": "section_template_schema_name",
          "preset_name": "section_template_schema_preset_name"
        },
        {
          "template": "section_template_schema_name",
          "preset_name": "other_section_template_schema_preset_name"
        },
        {
          "template": "other_section_template_schema_name",
          "preset_name": "section_template_schema_preset_name_of_other"
        }
      ]
    }
  ]
}
{% endschema %}

name (generator)

• Type: string
• Allowed characters: A-Za-z0-9
• Description: The name must be unique amongst all generators of one PageTemplate. It is used only internally to allocate inputs correctly despite changes of the externally used label.
• Typical Usage:

  "generators": [
      {
          "name": "my_generator_name",
          ...
      }
  ]

label (generator)

• Type: string
• Allowed characters: A-Za-z0-9+-; and single white-space inside
• Description: The label must be unique amongst all generators of one PageTemplate. It is use used externally in the EditorSidebar and can be changed anytime.
• Typical Usage:

  "generators": [
      {
          "label": "my generator label",
          ...
      }
  ]

sections (generator)

• Type: array of objects
• Description: Sections array inside generators of schema JSON consists of generator section objects, where each is used to define one section to be created.
• Typical Usage:

  "generators": [
    {
      "sections": [ 
        {
          "template": "section_template_schema_name",
          "preset_name": "section_template_schema_preset_name"
        },
        {
          "template": "other_section_template_schema_name",
          "preset_name": "section_template_schema_preset_name_of_other"
        },
        ...
      ]
    }
  ]

section (generator)

Each generator section object has template and preset_name field.

• Typical Usage:

  "generators": [
    {
      "sections": [ 
        {
          "template": "section_template_schema_name",
          "preset_name": "section_template_schema_preset_name"
        },
        ...
      ]
    }
  ]

template (generator)

Template field denominates one SectionTemplate by its schema name, hence, has to correspond with the name of a defined SectionTemplate.

preset_name (generator)

Preset_name field denominates one [preset] as defined in its SectionTemplate, denominated in template field.