Use external data from data resources

Data resources are the specific instance of data type which represents the JSON response of an API call. This could be a piece of CMS content or the result of a query like a list of products from a Product Information Management System (PIM) that matches certain search criteria. To use external data in your composition, pattern or entry you create a data resource to reference a specific instance of a data type.

Create a data resource#

Start by creating or editing a composition, pattern or content entry. As you select components in your composition or select fields from your entry, you'll see the available parameters or fields in the property panel.
Click the Insert variable icon in a parameter or type $$ and choose the "Insert dynamic token" option. This opens a drawer that lists the existing data resources and offers additional configuration options to add a data resource to the composition or entry.
Creating a new data resource
Select a data type from those available in your project. Most data types have additional configuration options, such as picking a specific product, or setting query result filters.
Review or adjust the proposed name of the data resource to match your use case and click on the Save button to add it to your composition or entry.

These steps assume that the author is going to fetch information at the composition or content entry level, and that data resources haven't been pre-configured through the use of patterns.

Manage data resources#

You can also manage data resources for a composition, pattern or content entry from the Canvas side rail in the data resources section. Managing data resources includes options to:

View source
Delete
Check the status of pattern data resources or loop data resources.

Manage data resources of a composition

Dynamic tokens#

The individual elements of data from the data resource can be connected to component parameters by inserting a dynamic token into a component parameter. A dynamic token is a text placeholder that stores the connection to an external data element or an dynamic input.

Example of a dynamic token connected to a blog post title

A dynamic token can combine with other text and multiple dynamic tokens can combine in the same parameter. For example, you can concatenate first and last name or format an address with dynamic tokens.

Example of formatting user profile data from https://randomuser.me using multiple dynamic tokens.

Use dynamic tokens in component parameters or entry fields#

You can connect data resources to component parameters or entry fields with dynamic tokens. For example, take a data resource that contains the data of a blog post which should display in a generic Card component. In this case you connect the properties of the blog post, which Uniform calls data elements, by placing dynamic tokens inside of the parameters of the Card component:

Blog post title -> Card title
Blog post image -> Card image
Blog post author -> Card description
Blog post category -> Card badge
Example connecting a blog post to a card component.

First you need to add a data resource to the composition, pattern or content entry.

Connect a data element to a dynamic token#

Once you have created a data resource, you can now select what information to bring into specific component parameters or entry fields. For example, if you have selected a "Blog post" from a CMS as your data resource, you can now browse to a specific blog post title for entry in a card component.

Example of selecting a piece of information from an integration for a composition.

Choose a component parameter or entry field to populate and click the Insert variable button next to the input. You will see the available information, usually in a nested display for complex items with many attributes.
About this step
You can also type $$ to open the Insert variable dialog
Inserting a dynamic token into a text parameter
Select the information you'd like to have brought into the composition and click Connect.
A dynamic token is placed inside the chosen parameter and the data from your system of record is now connected to your composition or content entry. You can also edit the dynamic token (to change to link a different piece of data) or disconnect the data connection. Disconnecting the data will replace the dynamic token with the current connected value in the field so you can either edit or delete it. By selecting and deleting a dynamic token via the backspace key you can remove it from the parameter.
Repeat this step with other component parameters that should be connected to the data resource

tip

The above steps show the bespoke method of connecting external data to compositions with data resources which enables getting quick results and using data in components in a flexible way.

However, in this model the data must be re-connected to each parameter each time you add a new component. This can be tedious for data-to-component linkages that are frequently reused, and can also present governance issues for authors who are new to connecting data.

For a simplified editing experience, Uniform supports patterns with pre-connected data that enable reusing components and data resources. An example of this might be to create a generic Card component, and then add an Author Card and Product Card pattern which is pre-connected to different data types. An author using the patterns need only select which author or product to use and not worry about the connections.

Dynamic inputs with data resources#

You can connect data resources to dynamic inputs to fetch dynamic data when a composition is connected to a project map node, and that project map node exposes dynamic inputs.

The project map node can have a dynamic segment, allowed query string keys, or both. Those dynamic values are passed to the composition attached to the node as dynamic inputs if:

The allowed query string is directly on the attached node.
There are dynamic segments in any ancestor or self node in the project map.

For example, if a composition that renders a product detail page and connects to a project map node such as /products/:productId, then it can connect the productId dynamic input it receives to a data resource that it's fetching from a PIM. This lets it fetch the specific requested product in the URL from the PIM instead of a single product selected by the composition author.

The dynamic input that a composition receives is made up of dynamic path segments on any ancestor of the connected project map node, as well as any allowed query string values on the directly connected node (not including ancestors).

Add or edit the data resource to connect the value of an dynamic input to the data resource option. Data resource options that can connect to dynamic inputs will show a small connect icon in front of their label. Click this icon and choose the dynamic input you wish to connect to. This places a dynamic token inside of the dynamic input form field.

Connect a dynamic input to a data resource configuration option

The value of a dynamic input can mix multiple dynamic tokens with other text strings. For example (inputName) and (inputName)-rocks-(inputName2) are both valid values for connecting a data resource to dynamic inputs. If you would like to disconnect from a dynamic input, click the connect icon again and choose Reset or delete the dynamic token using the backspace key.

A dynamic input connected to a data resource configuration option

When editing a composition that contains dynamic inputs it's useful to preview different input values. For example, you should preview a product detail page using any product you like. To change a dynamic input value, click on the dynamic input in the header of the composition editor. A drawer will open that lets you change the current preview value of any dynamic input. These values are saved in your browser, so you can pick up where you left off if you return later.

Previewing a dynamic route for a blog post