References

A reference is a relationship between two content entries. It allows an entry to benefit from the content in the linked entry without having to own or manage it. A reference is managed using a reference field.

Content reuse vs. content duplication#

A key benefit of references is reuse. For example, a blog post has an author. That author may write many blog posts. Rather than add the author’s name, avatar image, and bio to each blog post, we can create an Author entry containing that information, and reference it from each blog post they write.

Likewise, references allow multiple content types to benefit from the same supporting content. For example, a Recipe may have one or more Cuisines associated with it, while a Restaurant might also specialize in one or more Cuisines. The same Cuisine information can be used by both content types.

Manage shared content in one place#

References allow you to have a “single source of truth” for content. Using our examples above, if any information about an Author or Cuisine changes, once you update that particular entry, every entry that references it gets the updated information.

Create content taxonomies#

If you have a set of categories, tags, or other attributes that multiple content types may use, creating those as entries and referencing them allows you maximum flexibility in your taxonomies, with all the benefits of content reuse and centralized management. Also it allows you to enrich your taxonomies with additional content such as images, descriptions, and other metadata.

Examples:

  • Product brands
  • Blog categories
  • Game genres
  • Recipe cuisines
  • Statuses, e.g. priority, severity, availability

How to model taxonomies?

Classifying content with categories or tags can be modeled in many ways:

Use reference fields if you want your authors to be able to extend the list of options while being able to reuse existing entries. Another good reason to use references if your taxonomy needs additional information, such as descriptions or images, that should be managed as content entries.

Use single or multiple select fields if you want to limit the list of options to a pre-defined set (a so-called "controlled vocabulary") that is managed by content architects or when simple static text labels are sufficient for classification.

Fine-grained content curation#

When making recommendations about related content, using references allows you to specifically call out the most applicable suggestions. This gives you a level of control that simply grabbing the “most recent” or “others from this category” might not.

For example, you may want to specifically call out certain key accessories for a product, or suggest the most helpful/applicable FAQs relating to an online course. This specificity also allows you the option to A/B test these suggested items, and determine which ones your users find most useful.

Creating a reference field happens during the modeling step, as part of managing the associated content type.

A content type can have as many reference fields as are needed to support its purpose. Each reference field can be limited to allow only certain content types, as well a certain number of allowed references. See the field types guide for instructions on setting up a reference field.

Add a reference to an entry#

  1. On an entry that has a reference field as part of its content type, you will see the following presentation.

    Reference field for assigning 'Cuisine' references in a 'Recipe' entry
    Reference field for assigning 'Cuisine' references in a 'Recipe' entry

  2. You can reorder references in the list by dragging/dropping, or by using the Move options in the menu.

  3. To edit a referenced item, click on its name; it will open in a new tab.

  4. Upon clicking Add reference, a modal will open, showing selectable entries.

    Add references to a reference field
    Add references to a reference field
    1. This list conforms to any allowed content types set up on the field; you will not be able to select an entry that is not based on an allowed content type.
    2. You can add new entries of any allowed type by selecting Add entry. The new entry will open in a new tab.
    3. To quickly see and manage the currently selected items, you can switch the view from All to Selected (note: searching/filtering is not available within the Selected view).

  5. You can remove a referenced entry by opening the menu and selecting Remove, or by reopening the Add reference modal and deselecting a currently selected entry.

note

Removing a reference solely removes the relationship between the host entry and referenced entry; it does not affect the referenced content.

You may reference a content entry of any publishing status (Draft, Modified, or Published). Upon publishing the host entry, however, unpublished references will show up as warnings in the Publish Preflight window.

Warnings when publishing an entry with unpublished references
Warnings when publishing an entry with unpublished references

If you proceed with publishing and view the published entry, draft items will be removed, and modified items will return the last published version when resolving entries with references in Uniform's Edge Delivery API.

When using entries which have references to other entries in compositions or via the SDK or API, you will often need to resolve the referenced entries to access their content. As referenced entries might contain other references, you need to specify the number of levels to resolve.

For example, a Blog Post entry references an Author entry which in turn references a Company entry that the author works for. A Company entry also has references to Locations. If you want to display the employer of the author on the blog post, you will need to resolve all the references two levels deep to access any field of the Company entry.

LevelResolved references
Level 0Blog Post (current entry)
Level 1Blog Post -> Author
Level 2Blog Post -> Author -> Company
Level 3Blog Post -> Author -> Company -> Locations

When you add an entry as a data resource to a composition, or composition or component pattern, you need to specify how many levels to resolve on the data type of the data resource. Commonly you will have multiple data types per content type that represent the different archetypes (Single entry, Single entry by slug, Multiple entries, Query entries).

Multiple data types for a content type
Multiple data types for a content type

In the settings of the data type you can adjust the Levels to resolve setting. The default value is 1, which means that the data resource will be resolved to the first level of references. You can increase this value to resolve more levels of references to a maximum of 3 levels.

'Levels to resolve' setting for a data type
'Levels to resolve' setting for a data type

It is a best practice to keep the Levels to resolve setting low and only fetch the data you need. Over-fetching can negatively affect the performance and the payload size of the data resource and in consequence of the frontend application.

Usually data types that return a single entry will require a higher number of levels to resolve as they often are used for detail views that should include all the data of the referenced entries. Data types that return multiple entries or are query based often don't need to resolve more than one level of references as they are used for list views and content from nested references is not displayed.

Resolving references using the Canvas SDK is done by setting the resolutionDepth parameter on the getEntries method. This is only available when fetching entries using the Edge Delivery API which is the default behavior of the SDK. It is the same as providing the resolveData: true parameter.

import { ContentClient, } from '@uniformdev/canvas'; const contentClient = new ContentClient({ apiKey: <canvasApiKey>, projectId: <projectId>, }); // fetch entries of "recipe" content type // which has references to "Cuisine" entries const recipes = await contentClient .getEntries({ // resolve references two levels deep resolutionDepth: 2, filters: { type: { eq: 'recipe' }, }, limit: 20, orderBy: 'updated_at_DESC', }) .then(recipes => { return recipes.entries; }); // log the name of all referenced cuisine entries for each recipe recipes.forEach(recipe => { recipe.entry.fields.cuisines?.value.forEach(cuisine => { console.log(cuisine.entry.fields.name.value); }); });

For the /api/v1/entries endpoint of Uniform Edge Delivery API you can set the resolutionDepth parameter to specify for how many levels references should be resolved.

Last modified
Previous
Fields
Next
Blocks