Brightspot CMS Developer Guide

Data modeling for themes


With Styleguide you can add fields to individual templates so that the fields appear in the associated content edit forms. This feature helps expedite the development process by allowing front-end developers to do data modeling without involving back-end developers.

Tip
This section describes how to add fields to an individual template. If you find you are adding a global variable, consider using a theme's themeFields configuration key. For details, see Theme fields.


Use the following general steps to add a field to a Model for a specific theme.

  1. Change to the theme's Styleguide directory: cd brightspot-themes-frost/.
  2. Start the theme's Styleguide server: yarn styleguide.
  3. Open the theme's configuration file styleguide/_config.json.
  4. Add members to the styles key and save the file. The Styleguide server recompiles and packages the updated theme in a file /themes/<theme-directory>/target/brightspot-theme-<identifier>-SNAPSHOT.zip.
  5. Upload the updated theme's .zip file to the Brightspot server; for details, see Uploading a theme.
  6. Reload Brightspot in the browser. Upon reload, Brightspot detects the updated theme and loads it as well.

The following sections describe how to add various field types through a theme's configuration file.


Boolean fields appear as checkboxes. Open the theme's configuration file _config.json, and add a boolean entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "publicDomain": {
          "type": "boolean"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

Adding booleans.png
Adding a boolean field
Boolean field toggled on.png
Boolean field toggled on


Color fields appear as a color picker. Open the theme's configuration file _config.json, and add a color entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "textColor": {
          "type": "color"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New color field added.png
New color field added


Date fields appear as a date picker. Open the theme's configuration file _config.json, and add a date entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "dateOfBirth": {
          "type": "date"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New date field.png
New date field


A location field appears as a map of a user's location. Open the theme's configuration file _config.json, and add a location entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "targetLocation": {
          "type": "location"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New location added.png
New location added


Number fields appear as text boxes. Open the theme's configuration file _config.json, and add a number entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "quantity": {
          "type": "number"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New number field added.png
New number field added


Record fields appear as a selection field. Open the theme's configuration file _config.json, and add a record entry under the template's styles key. As a best practice, add a groups entry to limit the type of record the user can select.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "relatedArticle": {
          "type": "record",
          "groups": "brightspot.core.article.Article"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New records field added.png
New records field added


A region field appears as a map in which users can draw circles and polygons. Open the theme's configuration file _config.json, and add a region entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "targetRegion": {
          "type": "region"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New region added.png
New region added


Storage items appear as file selection controls. Open the theme's configuration file _config.json, and add a file entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "authorImage": {
          "type": "file"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New storage items field.png
New storage items field


String fields can appear as text boxes or a list of strings. For a text box, open the theme's configuration file _config.json, and add a text entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "attribution": {
          "type": "text"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New single string field added.png
New single string field added

For a list of strings, open the theme's configuration file _config.json, and add a list/text entry under the template's styles key.

{
  "styles": {
    "pathToTemplateFile.hbs": {
      "fields": {
        "attribution": {
          "type": "list/text"
        }
      }
    }
  }
}

The new field appears by default under the Overrides tab.

New list of strings added.png
New list of strings added


You can use options to customize fields you add through Styleguide. The options modify a field’s appearance or behavior. The following sections list the available options and how to implement them.

Overview of adding field options

Use the following general steps to add a field option to a Model for a specific theme.

  1. Start an instance of Brightspot.
  2. Change to the theme's Styleguide directory: cd themes/<theme-directory>/.
  3. Start the theme's Styleguide server: gulp styleguide.
  4. Open the theme's configuration file styleguide/_config.json.
  5. Add members to the styles key and save the file. The Styleguide server recompiles and packages the updated theme in a file themes//target/brightspot-theme--SNAPSHOT.zip.
  6. Upload the updated theme's .zip file to the Brightspot server; for details, see Uploading a theme.
  7. Reload Brightspot in the browser. Upon reload, Brightspot detects the updated theme and loads it as well.

The following sections describe how to add various field options through a theme's configuration file.

cms.ui.cluster

Displays a heading above the field. Useful for grouping fields under a heading.

{
  "primaryContributor": {
    "type": "record",
    "cms.ui.cluster": "Freelance author information"
  },
  "contributorBio": {
    "type": "text"
  },
}

For additional information, see @ToolUi.Cluster.

cms.ui.cssClass

Renders the field using the provided CSS class.

{
  "approvedBy": {
    "type": "text",
    "cms.ui.cssClass": "text-green-bold"
  }
}

You can define the CSS class in the Brightspot settings for the global site. Under Debug, set the Extra CSS field for example:

Extra CSS.png
Extra CSS

The rendered result appears as follows:

cms.ui.cssClass example.png
cms.ui.cssClass example

For additional information, see @ToolUi.CssClass.

cms.ui.dropDown

Displays a list with specified values.

{
  "Alignment": {
    "type": "text",
    "cms.ui.dropDown": true,
    "values": [
      {
        "label": "Left Alignment",
        "value": "alignleft"
      },
      {
        "label": "Center Alignment",
        "value": "aligncenter"
      },
      {
        "label": "Right Alignment",
        "value": "alignright"
      }
    ]
  }
}

Dropdown added to UI.png
Dropdown added to UI

For additional information, see @ToolUi.DropDown.

cms.ui.note

Displays explanatory note below the field.

{
  "articleBody": {
    "type": "text",
    "cms.ui.richText": true,
    "cms.ui.note": "Please, no more than 200 words."
  }
}

Article body.png
Article body

cms.ui.placeholder

Displays default placeholder text inside a text field.

{
  "breakingHeadline": {
    "type": "text",
    "cms.ui.placeholder": "Breaking news: "
  }
}

For additional information, see @ToolUi.Placeholder.

cms.ui.richText

Renders a text field as a rich-text editor.

{
  "freelancerBio": {
    "type": "text",
    "cms.ui.richText": true
  }
}

Freelancer Bio.png
Freelancer Bio

For additional information, see @ToolUi.RichText.

cms.ui.secret

Hides the text field's value; a Show Secret/Hide Secret control toggles the field's value in cleartext.

{
  "accountPassword": {
    "type": "text",
    "cms.ui.secret": true
  }
}

Hidden password.png
Hidden password

For additional information, see @ToolUi.Secret.

cms.ui.suggestedMaximum

Suggested maximal number of characters in a text field. Brightspot retains the entire string even if longer than the suggested maximum.

{
  "headlineLong": {
    "type": "text",
    "cms.ui.suggestedMaximum": 30
  }
}

Suggested maximum warning.png
Suggested maximum warning

For additional information, see @ToolUi.SuggestedMaximum.

cms.ui.suggestedMinimum

Suggested minimal number of characters in a text field. Brightspot retains the string even if shorter than the suggested minimum.

{
  "headlineShort": {
    "type": "text",
    "cms.ui.suggestedMinimum": 10
  }
}

Suggested minimum warning.png
Suggested minimum warning

For additional information, see @ToolUi.SuggestedMinimum.

cms.ui.tab

Indicates in which widget the field appears in the content edit form. If the widget does not exist, Brightspot creates it. Fields without this annotation appear in the Overrides widget.

Note
For the cms.ui.tab key to work, it must be used in conjunction with the inline key. For more information, see Placing fields in specified tabs.

{
  "wikipedia": {
    "type": "text",
    "cms.ui.tab": "Fact Checking"
  },
  "ciaFactBook": {
    "type": "text",
    "cms.ui.tab": "Fact Checking"
  }
}

For additional information, see @ToolUi.Tab.

hidden

Suppresses display of the field.

{
  "ghostWriter": {
    "type": "text",
    "hidden": true
   }
 }

For additional information, see @ToolUi.Hidden.

isRequired

Indicates user must provide a value for the field.

{
  "howManyBagsAreYouChecking": {
    "type": "number",
    "isRequired": true
  }
}

isRequired exampled.png
isRequired exampled

For additional information, see @Recordable.Required.


By default, new fields appear under the Overrides widget. With the inline key you can specify that new fields are placed in the Main widget. If used in conjunction with the cms.ui.tab key, the inline key allows you to place new fields in specified widgets.

In the following example, the inline key is set to true, forcing the darkTheme field to appear on the Main widget. If the inline key is set to false, or omitted, then the field appears in the Overrides widget.

{
  "styles": {
    "/core/list/List.hbs": {
      "example": "/list/List.json",
      "width": 1200,
      "height": 600,
      "scale": 0.25,
      "inline": true,
      "fields": {
        "darkTheme": {
          "type": "boolean"
        }
      }
    }
  }
}

In the next example, the inline key is used in conjunction with the cms.ui.tabkey. Two fields, wikipedia and ciaFactBook, are placed under the custom tab Fact Checking. A third field, sources, is placed under the Main tab given the absence of the cms.ui.tab key for that field.

{
  "styles": {
    "/core/article/ArticlePage.hbs": {
      "width": 850,
      "height": 1000,
      "scale": 0.2,
      "example": "/core/article/ArticlePage.json",
      "templates": "/article/*.json",
      "inline": true,
      "fields": {
        "wikipedia": {
          "type": "text",
          "cms.ui.tab": "Fact Checking"
        },
        "ciaFactBook": {
          "type": "text",
          "cms.ui.tab": "Fact Checking"
        },
        "sources": {
          "type": "list/text"
        }
      }
    }
  }
}

Displaying theme-specific fields in views

When you add fields to a model through _config.json, you need to add them to the view.

See also:

Displaying theme-specific fields in views

When you add fields to a model through _config.json, you need to add them to the view.

See also:

Displaying record fields

This section provides a full example of adding a record-type field to a theme’s view.

Displaying a record field within a view requires using an Indirect view model overlay value. The following example adds a record for an author to a theme’s content edit form, generates the view, and creates the view model.

Step 1: Add field to theme’s configuration file

In the theme’s _config.json, add a field of type record. (For an explanation of adding this type of field, see Adding records.) For example, add the following entry to /themes/<theme-dir>/styleguide/_config.json.

{
  "styles": {
    "/core/article/ArticlePage.hbs": {
      "fields": {
        "primaryContributor": { 
          "type": "record",
          "groups": "brightspot.core.person.Author"
        }
      }
    }
  }
}
  • Adds a selector field for authors to the ArticlePage template.

After you upload the updated theme, Brightspot displays the field in the content edit form.

New field displayed.png
New field displayed

In the theme’s parent template where you want the child view to appear, add the child record’s placeholder. For example, add the following line to /themes/<theme-dir>/styleguide/page/Page.hbs:

<p>{{primaryContributor}} contributed significantly to this article.</p>

In the previous snippet, the placeholder has the same name as the field you added in Step 1.

Step 3: Create child view for child view

  1. Change to the project’s root /styleguide/ directory. (This directory is in the same level as /themes/).
  2. As a best practice, create a new directory for your overlays, such as overlays/.
  3. Change to the directory you created in step 2.
  4. Create a template, such as PrimaryContributor.hbs, and enter the fields you want to include in the view.
    {{primaryContributorName}}
  5. Create a data file corresponding to the template, such as PrimaryContributor.json.
    {
      "_template": "PrimaryContributor.hbs",
      "primaryContributorName": "{{name}}"
    }
  6. In the project’s root directory, run mvn clean install. Brightspot creates a view interface in /frontend/target/generated-sources/styleguide/brightspot/view/. In this example, the view interface is /frontend/target/generated-sources/styleguide/brightspot/view/overlays/PrimaryContributorView.java.

Step 4: Create view model for record field

  1. Change to the project’s /core/src/main/java/brightspot/ directory.
  2. As a best practice, create a new directory for your overlay view models, such as overlays/.
  3. Change to the directory you created in step 2.
  4. Create a Java class with name parallel to the view. Continuing the example, create a file PrimaryContributorViewModel.java.
  5. Implement the view’s getters.
    package brightspot.overlays;
    
    import brightspot.core.person.Author;
    import brightspot.view.overlays.PrimaryContributorView;
    import com.psddev.cms.view.ViewModel;
    import com.psddev.cms.view.ViewModelOverlayValueEntryView;
    
    public class PrimaryContributorViewModel extends ViewModel<Author> implements PrimaryContributorView, ViewModelOverlayValueEntryView {
    
        @Override
        public CharSequence getPrimaryContributorName() {
            return model.getFirstName() + " " + model.getLastName();
        }
    }
  6. In the project’s root directory, again run mvn clean install. Brightspot compiles the new view model and adds it to the WAR file.

Step 5: Install updated theme

The previous step completely rebuilt your Brightspot project, including a new .zip file /themes/<theme-dir>/target/<theme-name-id>.zip. Install this .zip file as an update to the theme.

Step 6: Display view in browser

When you load the parent view in the browser, the child view also appears.

Child view displayed.png
Child view displayed

Displaying non-record fields

This section provides a full example of adding a field to a theme’s View. The example applies to all fields modeled in the file _config.json except those of type record.
Step 1: Add field to theme’s configuration file

In the theme’s _config.json, add a field. The previous sections describe how to add a variety of field types.

Adding a field to a theme’s configuration file

{
  "styles": {
    "/core/article/ArticlePage.hbs": {
      "fields": {
        "contributorBio": { 1
          "type": "text"
        }
      }
    }
  }
}
  • Adds a text field for a contributor’s bio.

After you upload the updated theme, Brightspot displays the field in the content edit form.

Field displayed in content edit form.png
Field displayed in content edit form

Step 2: Add field to template

Add the field’s placeholder to one of the templates within the available contexts. For example, in the file <theme-dir>/styleguide/article/ArticlePageFull.hbs, add the following lines:

<p>Meet your author</p>
<p>{{contributorBio}}</p> 

Step 3: Rebuild theme

  1. Change to /themes/<theme-dir>/.
  2. Run gulp styleguide. Brightspot packages the updated theme in a file target/<theme-name-id>.zip.
  3. In Brightspot, upload the .zip file as an update to the theme.
  4. Display the published page in your browser.
    Updated theme.png
    Updated theme
Previous Topic
Resource bundles - Theme Guide
Next Topic
Style variations
Was this topic helpful?
Thanks for your feedback.