- Build
- Features
Content Presets
Define content variations that editors can use to quickly create new pages and components.
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.
1
2
3
4
5
6
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 incontentSources
, 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:
- Stores the preset's content in the appropriate location.
- 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.
Pro Tip
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:
- Publish your shared presets to NPM (or similar registry)
- Add the package as a dependency in your project
- Use the
presetSource
option to add the proper path to the directory in the package containing the presets
1
2
3
4
5
6
7
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:
- When an editor adds the grid preset, they have some placeholder content for cards (rather than an empty space).
- 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.