chocoBRAIN Developer Documentation

# 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.

# 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.

# 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: text, textarea, rich_text, date, color, range, number, link_list, form, image, select
  • 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
}
  • Allowed input values: link object
  • For usage see link object.
  • Typical content:
    {
    "name": "my_link_name",
    "label": "my link label",
    "kind": "link"
}
  • 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"
        }
    ]
}

# 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"
            },
            ...
        ]
    }
]

# Preset

Each preset object has at least three fields: name, label and preview_image_url.

  • Typical usage: e.g. making a preview image available
    {% schema %}
{
    "schema_name": "my_schema_name",
    "css_class": "my_classes",
    "tag": "div",
    "presets": [
        {
            "name": "my_schema_preset_name",
            "label": "my_schema_preset_label",
            "preview_image_url": "https://www.mypics.de/my_image.jpg"
        }
    ]
}
{% 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",
        ...
    }
]

# Usage

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>

# rich_text

See richtext object

# image

See image object

See link object.

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 %}

←