Add Contentstack

Before you start

This guide helps you get started with the Contentstack-specific integration. For more general tips on working with external data sources, check out the guide on connecting to an external data source.

The Contentstack integration for Uniform brings your structured content from Contentstack into the composition layer, Uniform Canvas. Team members can now leverage your Contentstack content, along with data from any of your other sources, to create experiences without needing a developer.

This integration comes with these archetypes to help connect your Contentstack entities to your Uniform components:

To install the integration:

  1. Go to the Uniform dashboard.

  2. Select the team and project that you would like to install the integration into.

  3. Navigate to the Integrations tab using the main navigation bar. Select the Contentstack integration tile.

    add-contentstack-to-project
    The interface for adding the integration.
  4. Click the Add to project button that appears in the subsequent dialog. This will install the Contentstack integration and make the data source and archetypes available for when you are configuring new external sources. Learn more about connecting to external data sources.

Once you've installed the integration, the next step is to connect your Contentstack space to your Uniform project by creating a new data source.

  1. Navigate to Experience > Data Types. A data type is an element that can be retrieved from a data source, so the first step is to identify a data source.

  2. Create a new data source by clicking the Add data type button and select the "Create new" option under the Contentstack label.

    add-contentstack-data-source
    Add data type.
    add-contentstack-data-type
    Where to create a new data type from the available data sources.
  3. Provide details specific to the Contentstack space you are connecting to:

    FieldDescription
    RegionSelect your region.
    Stack API KeyThe API key for your chosen Stack within Contentstack. You can find this under Stack > Settings within Contentstack.
    Delivery tokenThe appropriate token for your chosen Stack. Find this under Stack > Settings > Tokens within Contentstack.
    Environment for Delivery Token (optional)Enter the environment associated with the delivery token given. This is optional.
    Branch (optional)Enter the branch associated with your chosen Stack. Find this under Stack > Settings > Branches within Contentstack.
  4. Name your data source. Choose a name that helps to inform your editorial users where the content is coming from. The name of the Contentstack organization and stack is a good option here.

Use multiple stacks

You may have more than one stack that you are using with Contentstack, perhaps to separate content used across different sites or different brands.

By repeating the preceding steps, you can support any number of stacks within a single Uniform project, allowing you to bring content together from across your Contentstack organization.

Before you start connecting Contentstack data to your Uniform compositions, it's important to first create some data types. Data types define which types of Contentstack data editors can use. This could be simple, like allowing an editor to select a single "hero" entity, or more perhaps a more complex query such as "the five latest news article entries."

Go to Experience > Data Types and click the Add data type button from below the Contentstack data source that you set-up earlier.

create-contentstack-data-type
Add a data type after selecting the data source.

Next, you will want to select and configure an archetype from the options below:

The query archetype will always return a list of content entries, up to the limit set by the editor in Uniform. This can be useful for dynamic queries where the most up-to-date information is needed, such as a "latest content" section.

contentstack-dynamic-query
Retrive information by a query.

Single entry#

The single entry archetype will always return a single entry from Contentstack, based on a selection by the editor in Uniform. This is useful for non-list elements that render as an independent item, such as a single "hero" entry or "article" entry. It can accept a variable from a dynamic token (such as a slug) and retrieve the corresponding entry.

contentstack-single-entry
Select a single entry from available data.

The multiple entry archetype lets an editor hand pick multiple entries to render as a list. This is useful when a small selection of specific entries is required, such as in a "featured articles" carousel.

contentstack-mulitple-entries
The interface for selecting multiple items from those available.

The entries by field archetype supports dynamic pages, allowing authors to leverage a slug as a dynamic input. You can use this data type for other uses as well, such as finding Contentstack entries by field value rather than using full-text search or other filters.

For example, suppose you have a project map node with a dynamic path segment such as the slug post, where post is a dynamic input for a blog post coming from Contentstack. You can create an entries by field data type to connect the post dynamic input with the slug field of the data resource.

You can find more information about using dynamic inputs with data resources in the composition guides, or learn more about using dynamic routes with project map in the URL management section.

contentstack-entries-by-field
Select a field on which to search for content to pull into the component.

Once you have configured your data types, you will be ready for the final step of connecting your Contentstack data to your components and compositions from within Uniform Canvas.

For commonly used components, Uniform recommends using patterns. This is the best approach when content architects want to create a reusable connection between a data type and a component, and avoids mapping data every time you use Contentstack data.

With patterns, you define exactly how a component (or set of components) should be configured ahead of time, including the data bindings to external services. Once configured, composing with Contentstack is as simple as selecting the pattern you need (such as a Hero),just like you would select a standard component. The difference is that this time, you can also select the Contentstack resource that should supply the data and Uniform will handle the rest.

selecting-pattern
Selecting the pattern to add.
implemented-pattern
All pattern bindings can be updated by changing the data resource.

To learn more about how to use patterns, check out the pattern guide.

The most granular approach for bringing your Contentstack data into Uniform is to connect a resource to a component field directly. To do this, open the composition and component you want connect to Contentstack data.

  1. Select a field within the component that you wish to connect Contentstack data to.

  2. Click the ••• on the top left of the field you can open up the data resource mapping dialog.

    connect-data-resource
    Fields that support data connections will have an icon by which you access data resources.

    From here, you will be guided through the process of setting a data resource for the composition, if none are available already. To set up the data resource just provide a name. Choose something that connects it to the resource is used in the composition (such as "Featured Article"), and select your data by using the data types you defined earlier.

    selecting-a-resource
    Selecting a data resource to connect to the composition.
  3. After you select your data resource, map the appropriate field from the data resource to the parameter on your component. For example, map the title field from your Contentstack entry to the title field of your Uniform component.

    field-mapping
    Mapping the field from Contentstack to the parameter.

    Now that you have a data resource configured, you can use this resource to connect fields across the entire composition without needing to recreate the resource. This also means that if you update the data resource to a different selection or query, then all the components that map to the original data resource will update automatically with no remapping.