Botsquad documentation logo

Content management

Now that we know how we can store data inside our bot, without it touching our bot’s code directly, you might want to give technically skilled people access to these files, in order for them to edit them.

However, some people can be afraid of “code” views, even if it is just a YAML file. And they risk breaking the bot by entering incorrect data, or destroying the entire file.

To address this, Botsquad incorporates a basic content management system (CMS). It is possible to invite users into the studio, giving them just the editor access role. With this role, they cannot see or edit a bot’s code, and they also cannot edit any data files directly.

The CMS lives in a dedicated tab on the editor page, called Content. It is composed of multiple parts, called Content sections. Each section has a descriptive title and an icon, to indicate its purpose.

Content sections

When you have created your first content definition, a new content tab is enabled in the bot editor, showing the available content sections. It looks like this:

ddl

On the left side, there are the various content sections; in this case there is only one, named “Configuration”. In the middle, it shows the actual configuration form. Any data you enter in this form, gets saved in a YAML file in the bot’s scripts.

When you change the content, you can try it out directly in the bot by clicking the Run button.

You’ll notice that, as soon as you change any data, you’ll see the publish box pop up. Click Publish to put the changes live, or revert to undo any changes to the data.

Editors only see this “Content” tab, not the Files or Published tabs.

Content definition YAML

Every content section is represented by a single content definition file: a special YAML script which is part of your bot.

To create a content section like the one above, start by creating a Content definition YAML file in your bot:

ddl

Then, hit publish, and immediately the Content section becomes visible in the studio.

The content definition you added looks like the following:

# This is an example "Content Definition" YAML file.
# Files like these define sections of the bot's CMS. Each section
# creates either a form or a data table, which can be edited by users
# (editors) that do not have access to this bot's code.
#
# For more information about the CMS feature:
# http://doc.botsquad.com/dsl/cms/
type: form # or 'table'

# Define where the content gets stored
storage:
  type: script # stored inside a script file
  script_title: config  # Please create a YAML file with this title!

# title of the CMS section
title: Configuration

# see http://blueprintjs.com/docs/v2/#icons for possible icon names
icon: cog

# Optional extra description / help text
description: This is a configuration form

# The form definition, defines the data that can be edited
form:
  # the JSON schema, describing the form
  schema:
    type: object
    properties:
      account_name:
        type: string
        title: Account name
      is_advanced:
        type: boolean
        title: Enable advanced features
      is_ludicrous:
        type: boolean
        title: Enable ludicrous mode
  ui_schema:
    # specifies the ordering of the fields
    ui:order:
      - account_name
      - "*" # all the others

It is heavily commented and should be pretty much self explanatory. A content definition like this defines a section in the CMS part of the bot, with a title, an icon, a possible description, and the definition of the actual form. The storage section defines where the content should be stored. For now, content is always stored in a script, so you need to make sure that there is a data script with the same name as given in the storage.script_title key.

JSON Schema

The form.schema key is the most important key of the content definition: the schema defines the shape of the content. For this, we use JSON schema, which is a way to describe how data looks. And in our case, it also describes how the form looks that will be shown in the CMS.

For composing the form, we use the React JSON Schema Form library. So most options described there are functional and usable in the content definition. The Form customization section especially, goes into detail on the available customization options.

Specialized content widgets in forms

By using ui:widget in the UI schema, it is possible to use form widgets that are specialized for editing a specific type of content. The following are supported:

CSV / spreadsheet data

Besides defining forms, there is also a second content management option, which is used to edit CSV files. By specifying type: table in the content definition, the content section presents an Excel-like spreadsheet data:

ddl

The contents of the spreadsheet is fully editable, and the data itself is stored in a CSV file in your bot’s scripts.

The names of the columns are stored in the content definition file, as you don’t want content editors to change these names.

The corresponding content definition file looks like this:

type: table
storage:
  type: script
  script_title: users
title: Users
icon: people
table:
  columns:
  - id
  - first_name
  - last_name
  - age