Overview of Referral Field

Use reference fields to connect items from different Collections.

The referral field is a Collection field that you can include in a CMS Collection. Rather than utilizing an option field that restricts you to select from a list of predefined values, the referral field allows you to select from any item in another Collection. Subsequently, you can utilize the information of the referred item in Collection lists and Collection pages.

For instance, there might be a text field on a Collection page that is dynamically linked to a Collection named “Recipes”. Then, an item in a Collection named “Authors” (e.g., an author) can be referred to in the “Recipes” Collection using a referral field.

In case the author is linked to the “Recipes” Collection page through a referral field, and you later update that author’s details, it will automatically update on the Collection page due to the referral field connection.

Some common applications of the referral field are:

  • A “Blog posts” Collection referring to an “Authors” Collection
  • A “Recipes” Collection linking to an “Authors” Collection
  • A “News articles” Collection referencing a “Category” Collection
  • A “Lessons” Collection linking to a “Courses” Collection
Attention: To refer to multiple items in a different Collection (e.g., referring to an author’s name and biography), employ the multi-referral field.

Throughout this tutorial, you will learn:

  1. Steps to establish a referral field
  2. How to cite items
  3. How to utilize the referral field in your site layout
  4. How to refine a Collection list utilizing the referral field
  5. How to implement conditional visibility using the referral field

Steps for Establishing a Referral Field

You can introduce a referral field to a new or existing Collection. To add a referral field to an existing Collection:

  1. Position the cursor over the Collection where you want to integrate the referral field
  2. Press the settings “cog” icon to reveal the Collection settings
  3. Tap on Add new field within the Collection fields segment
  4. Choose the Referral field type
  5. Incorporate a Label
  6. Include Help text, if desired
  7. Pick a Collection to refer to from the Collection dropdown
  8. Select “This field is required” if you wish to make the field mandatory

If you have not yet created a Collection, discover how to append a Collection to your site.

The Reference field type is highlighted in the “Add new field” section of Collection settings.
An example Reference field named “Author,” which has the Collection set to the example “Recipe Authors” Collection.

Crucial: The number of referral fields per Collection is restricted based on your Site plan. Starter, CMS, and Ecommerce Standard Site plans can accommodate up to 5 referral fields per Collection. Business, Ecommerce Plus, Ecommerce Advanced, and Enterprise Site plans can have up to 10 referral fields per Collection. Basic Site plans do not include referral fields. Discover more regarding site plans.

Citing Items

After adding a referral field to a Collection, you can enter that Collection’s Collection items and allocate a value for the field in each Collection item. There, you have the flexibility to select any item from the alternate Collection you are referring to in the referral field settings.

Using the Referral Field in Site Design

You can extract data from a referred Collection and include it in a Collection page or a Collection list within your site design. You can establish a connection between a field and an element or a style.

Establishing Connections

When you integrate any element into a Collection list or onto a Collection page, you can source the content for that element from the fields of a referred Collection.

For instance, you can link a recipe’s title in your Recipe Collection to a Heading element, and an author’s name to a text element.

A text element is connected to the Name plain text field in an example referenced “Author” Collection.

Establishing design connection

In case a referred Collection possesses a color palette or an image placeholder configured on each Collection unit, these aspects can be utilized to customize the background hue, border accent, text hue, or background visual in the design of your website.

The “Get BG Color” setting is checked in Dynamic style settings.

Sorting a Collection list through the relational field

There exist 3 methods to employ a relational field for sorting Collection lists. In the provided scenarios, we will take advantage of a “Recipes” Collection linking to an “Authors” Collection.

  • Arrange as per a specific item in the connected Collection (e.g., display solely the recipes related to a particular author)
  • Sort based on the current page’s reference (e.g., display a compilation of other recipes by the same author as the current page’s author)
  • Select based on the current page’s reference on the linked Collection page (e.g., on the Authors Collection page, showcase all recipes linked to that author)

Crucial: Sorting by reference fields is solely applicable for Collection lists linked to a Collection containing a relational field.

Arranging as per a specific item in the linked Collection

It is viable to organize Collection lists through implementing the relational field. This enables the presentation of specific entities adhering to the selection criteria.

An exemplar of this could involve creating a Collection list titled “Featured recipes.” This list could be sorted so that it refers exclusively to the elements (the recipes) in a “Recipes” Collection having a ‘featured’ flag enabled.

A Collection list filter is set to filter Collection items with a “Featured recipe” toggle set to “on.”

Sort by current page’s reference

You have the ability to incorporate a Collection list to a Collection page and feature solely the entities that share the same reference item as the Collectionpage’s referenced item. 

For instance, on a “Recipes” Collection page, it is possible to exhibit a list of other recipes attributed to the same author as the author referenced on the current page. This is a prevalent strategy to display “Related content” sections. 

To achieve this, apply a filter to the current page’s Collection list where the “Author” reference field matches the “Author of Current Recipe.”

A filter is set on a Collection list where the “Author” equals the “Author of Current Recipe.”

Sort by current page’s reference on the linked Collection page

Additionally, you can filter a Collection list on the linked Collection page. 

To illustrate, on your “Authors” Collection page, you can present all recipes (from a “Recipes” Collection) referencing that author. Insert a Collection list, link it to the “Recipes” Collection, and implement a filter where the “Author” reference field equals theCurrent Recipe Author.”

A filter is set on a Collection list so that the “Author” equals the “Current Recipe Author.”

Gain further insights on Collection list filters.

How to configure conditional visibility via the relational field

Conditional visibility can be set to unveil or obscure particular elements in a Collection list or on a Collection page through:

  • The relational field itself
  • Any fields from the linked collection

Where is this type of criteria applicable?

This specific criterion can only be established within a Collection list linked to the Collection possessing the relational field or is on the Collection template page of this Collection.

For example, if a Collection named “Events” features a relational field linked to a Collection named “Locations”, conditions can be added based on the reference field “Locations” or any fields from this linked collection at the following instances:

  • Within any Collection list associated with the “Events” Collection
  • On the “Events” template page

What types of criteria can be defined?

The following criteria based on the relational field itself can be incorporated:

  • When the relational field Is established or Is not established
  • When the relational field Matches or Contrasts a specific value

Furthermore, a criterion based on a specific field from the linked collection can be created. The category of the criterion relies on the kind of the Collection field.

Illustration: A criterion centered

on a pasture from a alluded set

In this instance, we possess a Collection list linked to an “Events” assortment. The “Events” Array points to a “Locations” selection.

Within this Collection list associated with the “Events” assortment, we hold various field qualities from the “Locations” Assortment connected to textual fragments. We’ve appended designations for each attribute we want to portray (for instance, “Date”, “City”, etc.). The designations and the attributes possess a presentation configured to inline so they materialize adjacent to each other.

We can establish circumstantial perceptibility on a textual piece so it only emerges when the attribute is designated in the Compilation item:

  1. Pick the textual piece (e.g., “City”)
  2. Unlatch Element settings panel > Circumstantial perceptibility
  3. Tap the “plus” symbol to the right of “Conditions
  4. Determine the field from the alluded assortment in the initial dropdown — for this illustration that would be City (Location)
  5. Opt for Is set within the secondary dropdown
  6. Conserve the stipulation
A condition is added so that the text block element is visible when City (Location) is set.

Within this illustration, we further possess a “Map link” which we wish to have accessible to website visitors when they hit the city denomination. To achieve that, we’re employing a Text link that withdraws the text from the “City“field and the URL from the “Map link“field.

A text link pulls the URL from the “Map link” field and the text from the “City” field. Both fields are linked to the “Events” Collection.

If some locations don’t possess a map link, we wouldn’t like to exhibit a text link when there isn’t a link to proceed to. In such a scenario, we can utilize conditional visibility. 

We can append a stipulation to this Text link so it displays solely when the “Map link“field of the alluded “Locations” Assortment Is set (e.g., when a map link has been added to the Compilation item).

A condition is set so that the text link is visible only when the “Map link (Location)” is set.

Next, we can attach a Text block (rather than a Text link) and link it to the “City” attribute. Subsequently, we can configure a stipulation of this Text block for when the “Map link” field Is not set. This method, merely the city title (devoid of a link) will be visible when there isn’t a “Map link” configured in the “Locations” Compilation item.

A condition is set so that the text block is visible when the “Map link (Location)” is not set.

To assure the Text block is inline with the label, you can include a class to it and configure the presentation to inline.

Instance: A condition grounded on an alluded attribute

We’ve appended all these location-connected designations and attributes within a div block, which we styled beneath the class name “Location details.” Leveraging circumscribed visibility, we can guarantee this complete div block only manifests when the “Location” reference attribute is designated for each event in the “Events” Assortment. To achieve this:

  1. Select the “Location details” div block
  2. Unlatch Element settings panel > Circumstantial visibility
  3. Tap the “plus” symbol to the right of “Conditions
  4. Opt for your reference attribute (e.g.,Location (Reference)”) in the primary dropdown
  5. Choose Is set within the secondary dropdown
  6. Conserve the stipulation
A condition is added so that the div block is visible when “Location (Reference)” is set.
Note: The reference attribute cannot be utilized for sorting.
Ewan Mak
Latest posts by Ewan Mak (see all)