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 or pattern you create a data resource to reference a specific instance of a data type.

To create a data resource:

1. Start by creating or editing a composition from Content > Compositions in Uniform. As you add components to your composition, you'll see the available parameters in the property panel.

2. Add a component to your composition. 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.

   

   Creating a new data resource

3. 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.

4. 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.

These steps assume that the author is going to fetch information at the composition 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 or pattern 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#

You can connect data resources to component parameters 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 -> Hero badge

  

  Example connecting a blog post to a hero component.

To create a data resource:

1. Start by creating or editing a composition from Content > Compositions in Uniform. As you add components to your composition, you'll see the available parameters in the property panel.

2. Add a component to your composition. 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.

   

   Creating a new data resource

3. 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.

4. 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.

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

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 fields in your component. 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 hero component.

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

1. Choose a parameter to populate and click the Insert variable button next to the field. 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

2. Select the information you'd like to have brought into the composition and click "Connect."

3. A dynamic token is placed inside the chosen parameter and the data from your system of record is now connected to your composition. 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.

4. Repeat this step with other component parameters that should be connected to the data resource

Data resources in Canvas#

You can also manage data resources for a composition or pattern 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 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