Using the Contentful integration

The Contentful integration for Uniform brings your structured content from Contentful into the composition layer, Uniform Canvas. Team members can now leverage your Contentful 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 Contentful entities to your Uniform components:

• Single entry selector: For selecting a single entry
• Multi-entry selector: For selecting multiple entries
• Asset selector: For selecting images and files
• Query: For creating a dynamic query (for example, the 5 most recent items)

Install the integration#

To instal 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 Contentful integration tile.

   

4. Click the Add to project button that appears in the subsequent dialog. This will install the Contentful 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.

Configuring the data source#

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

1. Navigate to Content > 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 click the Add data type button and select the "Create new" option under the Contentful label.

   
   

3. Provide details specific to the Contentful space you are connecting to:

   Field	Description
   Space ID	The ID for your Contentful space. (e.g xx53w0a6mijw)
   Environment ID (optional)	You can specify a specific Environment ID to use when requesting data from this space. If left empty, this field will default to master.
   Content Delivery API Token	If you don't have one already, you can provision this key from the API settings page in your Contentful space settings. You will need to provide the key for the "Delivery API," not the "Preview API."

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 Contentful organization and space is a good option here.

Contentful data types#

Before you start connecting Contentful data to your Uniform compositions, it's important to first create some data types. Data types define which types of Contentful 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 Content > Data Types and click the Add data type button from below the Contentful data source that you set-up earlier.

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

Archetype: Single entry#

The single entry archetype will always return a single entry from Contentful, 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.

Archetype: Multiple entries#

The multiple entry archetype lets an editor hand pick 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.

Archetype: Query#

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.

Archetype: Asset selector#

The asset selector is useful for browsing media assets stored within Contentful for cases when you want to replace images or documents with media from within your Contentful space directly.

Connect data to components and patterns#

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

Patterns#

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 Contentful 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 Contentful is as simple as selecting the pattern you need (such as a Contentful Hero),just like you would select a standard component. The difference is that this time, you can also select the Contentful resource that should supply the data and Uniform will handle the rest.

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

Parameters#

The most granular approach for bringing your Contentful 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 Contentful data.

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

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

   

   From here, you will be guided through the process of setting a data resource for the composition, if none are available already. Setting up a data resource is simple, 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.

   

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 Contentful entry to the title field of your Uniform component.

   

   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.