Data Modeling

You can add fields to the content edit form at the theme level. This feature avoids cluttering the content edit forms with many fields that you may not need for a particular theme. For example, suppose you have a publication that provides product reviews, and another publication that provides product reviews along with PDFs of specifications. You can apply a new theme to the second publication, and customize the content edit form with StorageItem fields for the PDFs.

You add fields to a theme’s templates. As you assemble those templates into parent templates, the additional fields are available in the parent templates as well.

Overview

Use the following general steps to add a field 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/<theme-directory>/target/brightspot-theme-<identifier>-SNAPSHOT.zip.
  6. Upload the updated theme’s ZIP file to the Brightspot server; for details, see Uploading a New 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 types through a theme’s configuration file.

Adding Booleans

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.

../../_images/styleguide-boolean.png

Adding Strings

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.

../../_images/styleguide-string.png

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.

../../_images/styleguide-string-list.svg

Adding Storage Items

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.

../../_images/styleguide-file.png

Adding Numbers

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.

../../_images/styleguide-number.png

Adding Dates

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.

../../_images/styleguide-date.png

Adding Colors

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.

../../_images/styleguide-color.png

Adding Records

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.

../../_images/styleguide-record.png

Adding Regions

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.

../../_images/styleguide-region.png

Adding Locations

A location field appears as a map with a marker in the center of the United States. 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.

../../_images/styleguide-location.png

Field Options

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.

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"
  },
}
../../_images/styleguide-cluster.png

For additional information, see @ToolUi.Cluster.

cms.ui.cssClass

Renders the field using the provided CSS class.

{
  "approvedBy": {
    "type": "text",
    "cms.ui.cssClass": "large-approved-by"
  }
}
../../_images/styleguide-css.png

For additional information, see @ToolUi.CssClass.

cms.ui.dropDown

Displays a drop-down 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"
      }
    ]
  }
}
../../_images/styleguide-dropdown.png

For additional information, see @ToolUi.DropDown.

cms.ui.note

Displays explanatory note above the field.

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

For additional information, see @ToolUi.Note.

cms.ui.placeholder

Displays default placeholder text inside a text field.

{
  "breakingHeadline": {
    "type": "text",
    "cms.ui.placeholder": "Breaking news: "
  }
}
../../_images/styleguide-placeholder.png

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
  }
}
../../_images/styleguide-rte.png

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
  }
}
../../_images/styleguide-secret.png

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
  }
}
../../_images/styleguide-maximum.png

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
  }
}
../../_images/styleguide-minimum.png

For additional information, see @ToolUi.SuggestedMinimum.

cms.ui.tab

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

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
  }
}
../../_images/styleguide-required.png

For additional information, see @Recordable.Required.

Placing Fields in Specified Tabs

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

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

{
  "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.tab key. 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.

Displaying Record Fields

This section provides a full example of adding a record-type field to a theme’s View. For details about adding fields of any type other than record to a theme’s View, see Displaying Non-Record Fields.

Displaying a record field within a View requires using an Indirect View Model Overlay Value. In the following example, we add a record for an author to a theme’s content edit form, generate the View, create the ViewModel.

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "styles": {
    "/core/article/ArticlePage.hbs": {
      "fields": {
        "primaryContributor": {
          "type": "record",
          "groups": "brightspot.core.person.Author"
        }
      }
    }
  }
}

In the previous snippet, lines 5–8 add a selector field for authors to the ArticlePage template. After you upload the updated theme, Brightspot displays the field in the content edit form. (For details about uploading an updated theme, see Upgrading a Theme to New Release.)

../../_images/template-record-field-view-cef.png

Step 2: Add Record Placeholder to Parent Template

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 file, 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 file, 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 ViewModel 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 ViewModels, such as overlays/.

  3. Change to the directory you created in step 2.

  4. Create a Java class with name parallel to the View. In our 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 ViewModel 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. For details, see Upgrading a Theme to New Release.

Step 6: Display View in Browser

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

../../_images/template-record-field-view-rendered.png

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. (For details about displaying fields of type record, see Displaying Record Fields.)

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "styles": {
    "/core/article/ArticlePage.hbs": {
      "fields": {
        "contributorBio": {
          "type": "text"
        }
      }
    }
  }
}

In the previous snippet, lines 5–6 add a text field for a contributor’s bio. After you upload the updated theme, Brightspot displays the field in the content edit form. (For details about uploading an updated theme, see Upgrading a Theme to New Release.)

../../_images/template-field-view-cef.png

Step 2: Add Field to Template

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

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

In the previous snippet, the placeholder in line 2 corresponds to the field name in line 5 in Step 1.

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. For details, see Upgrading a Theme to New Release.

  4. Display the published page in your browser.

    ../../_images/template-field-view-rendered.png

See also:

Reusing Fields

You can define a field once at the top level of a _config.json file, and add it in several places to theme’s Content Edit Forms. The following snippet demonstrates how the same checkbox appears in two content edit forms within the same theme.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "fields": {
    "spellingVerified": {
      "type": "boolean"
    }
  },
  "styles": {
    "/core/author/AuthorPage.hbs": {
      "fields": ["spellingVerified"]
    },
    "/core/article/ArticlePage.hbs": {
      "fields": ["spellingVerified"]
    }
  }
}

In the previous snippet—

  • Lines 2–6 define globally available fields for the current theme. In this case, one field spellingVerified is available.
  • Lines 8–10 add the field to the AuthorPage’s content edit form. The fields key on line 9 refers to an array, so you can add multiple fields defined in the top-level fields element.
  • Lines 11–13 add the same field to the ArticlePage’s content edit form.
../../_images/replicated-json-fields.svg

Hiding Style Variations

Brightspot provides many style variations for different components. For example, an article’s page may have the following available variations: one column, two columns, large image on top, side bar, and many others. At the theme level, you can suppress a style variation from appearing in the content edit form for a given component. In the following example, we suppress ArticlePageWithSidebar as a variation for article pages.

  1. Change to themes/<theme_name>/styleguide/.
  2. Open the file _config.json.
  3. Identify the template containing the template you want to suppress. (You can often find the template by searching for the label appearing on the UI. For example, if you want to suppress a template that appears with the label Article Page With Right Sidebar, search for that label inside _config.json.)
  4. Add the object "hidden": true to the template you want to suppress.
  5. Save the file.
  6. Rerun styleguide: in the directory themes/<theme_name>/styleguide/ run gulp styleguide. Brightspot packages the theme in a ZIP file under themes/<theme_name>/target/.
  7. Upload the updated theme package. For details, see Upgrading a Theme to New Release.
  8. Reload the content edit form.

For example, the following snippet from a theme’s _config.json file specifies a parent template ArticlePage.hbs comprised of two child templates: ArticlePageWithSidebar.hbs and ArticlePageFull.hbs. Line 6 suppresses the appearance of the first template in the theme’s content edit form for the parent template.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "styles": {
    "/core/article/ArticlePage.hbs": {
      "templates": [
        {
          "hidden": true,
          "displayName": "Article Page With Right Sidebar",
          "template": "/article/ArticlePageWithSidebar.hbs",
          "example": "/article/ArticlePageWithSidebar.json"
        },
        {
          "displayName": "Article Page Full",
          "template": "/article/ArticlePageFull.hbs",
          "example": "/article/ArticlePageFull.json"
        }
      ]
    }
  }
}
../../_images/visible-template.svg ../../_images/hidden-template.svg