Content Presets

Presets are predetermined variations of content that can be used to provide content editors with a quick way to create new, visually-rich pages and components.

With Stackbit, both pages and components are represented by content models, and presets must be defined against a specific model.

How Presets Work#

Preset definitions are read by Stackbit, and the results displayed when a content editor chooses to create a page or new component. When the page is created or the component added to a page, Stackbit adds the new content to the site based on the preset's configuration.

An example of adding a new component from a preset can be seen in the image above.

By default, presets are stored in files in the .stackbit/presets directory within your repository. However, presets can be stored in a remote content source if configured correctly. See below for more information on both of these scenarios.

File-Based Presets#

By default, Stackbit looks for presets defined in the .stackbit/presets directory. This can be customized using the presetSource option.

Preset files each define one or more presets for one particular content model used in your site. Learn more about the preset configuration API.

{
  "model": "Card",
  "presets": [
    // preset config ...
  ]
}

API-Based Presets#

Stackbit will store presets in a remote content source under the following conditions:

• The contentSources property is used to define the content source.
• A defined content source includes a stackbitPreset model, with the following fields:
  • label (string)
  • thumbnail (media/image)
  • data (json/text)

Using this feature has the following side-effects and conditions:

• Stackbit will use the first stackbitPreset model it finds from sources defined in contentSources, starting from the first element in the array.
• File-based presets can not also be used and the presetSource property will be ignored.

Creating Presets#

The easiest way to create presets is to use the Save as Preset feature, available to content editors.

Creating a new preset using the Save as Preset feature does the following:

1. Stores the preset's content in the appropriate location.
2. Generates a thumbnail preview of the component, and places the file in the appropriate source. (For file-based presets, this is in the .stackbit/presets/images directory.)

Building Presets from Scratch#

Because presets are stored as JSON files or records in your content source, you can also build presets from scratch.

If doing so, we recommend working locally and using the preset configuration API reference to see the available options.

Sharing Presets Across Projects#

The presetSource property makes it possible to load presets from the node_modules directory in your project. This unlocks the ability to share presets across multiple projects.

To add shared presets to your project:

1. Publish your shared presets to NPM (or similar registry)
2. Add the package as a dependency in your project
3. Use the presetSource option to add the proper path to the directory in the package containing the presets

export default {
  presetSource: {
    type: 'files',
    presetDirs: ['node_modules/some-package/.stackbit/presets', 'my-presets'],
  },
  // other properties ...
}

Developing Shared Presets#

When building shared presets, you want to make sure they are going to be available to your shared projects before publishing. To do so, we recommend working locally with an example project that links to some other local directory (or Git submodule) to ensure the presets are configured properly.

Handling Nested Objects#

Stackbit page models can include fields which embed object models inside the page. Object models can also recursively include fields that embed structured content representing another object model.

In other words, as components are represented by object models in Stackbit, components can have subcomponents which are also represented by an object model.

While presets are defined at the model level, they can also include any necessary embedded content (i.e. children). For example, a CardGrid preset can also include embedded content for an array of Card components. Using this preset would then also generate the provided children.

Standalone Child Presets#

If child components are represented by a model, you can also create presets for them. Using the example above, while a CardGrid preset could include Card presets, you could also have separate definitions for Card presets.

The benefit of this is that:

1. When an editor adds the grid preset, they have some placeholder content for cards (rather than an empty space).
2. Editors also have a series of options when creating new cards. After they've added a grid, they can then move quickly in adding new cards as needed.

Dynamic Content References#

Some API CMSs don't have the concept of embedded models. For example, with Contentful, everything is a reference. Therefore, you must understand how to handle referenced content, as you may want to reuse existing content in some cases, but duplicate new records in other cases.

See the appropriate integration guide for your content source for more information.