Reference

The Reference field allows you to create references to entries of the same content type or other content type(s). It lets you access and use entries of other content types as an input within your field.

The process of creating references of the same content type is known as “Self Referencing” and creating references of other content type(s) is known as “Include Referencing.”

Let's look at them in detail to understand their differences better.

Self Referencing

In Self Referencing, the Reference field allows you to create references to entries of the same content type. It lets you use entries of the same content type as input.

Let's say you are creating an e-commerce app consisting of “Category,” “Brand,” and “Product" content types. Now, you want to add the functionality to recommend products that are related to the product chosen by a user via the app. For example, if a user buys a mobile phone belonging to XYZ brand, they should get recommendations of headsets, chargers, or mobile phone covers of the same brand.

In this case, you need to add a Reference field in the “Product” content type of your e-commerce app and select “Product” as the reference, since all the products in the app belong to the same “Product” content type.

To do this, you will first add a “Reference” field in your e-commerce app and rename it as “Recommendations” and select the “Product” content type as the reference. Now, whenever content managers create entries for “Product,” they will be able to list all the products that are associated with the entry. Users can select the required recommended products and go ahead with filling the data in other fields.

The “Reference” field possesses certain properties that you can change anytime as per your requirements. The properties that can be modified are “Display Name,” “Unique ID,” “Placeholder Value,” “Instruction Value,” “Help Text,” “Mandatory,” “Multiple,” “Non-localizable,”and “Referenced Content Type.”

Additional Resource: If you want to hide/show a field when certain conditions are met, you can use Field Visibility Rules.
To get a clear idea of the Reference field and its usage, you can refer to our Reference vs Select vs Tags fields article.

Include Referencing

In Include Referencing, the “Reference” field allows you to create references to entries of a single or multiple content type(s). It lets you use entries of the selected content type(s) as input.

There are two subtypes of Include Referencing - “Single Content Type Referencing” and “Multiple Content Type Referencing.” Let’s look at them in detail.

Additional Resource: To know the difference between Single and Multiple Content types, refer to the Single vs Multiple guide.

Single Content Type Referencing

In Single Content Type Referencing, the Reference field allows you to create references to entries of a single content type.

Example: Let’s say you want to create news articles, and you want to link each news article to its author. In this case, you will begin by creating two content types: “News Article” and “Authors.” In your “News Article” content type, you can add a Reference field named “Author(s)” that points to the entries of the “Authors” content type for author data.

Now, whenever content managers create entries for “News Article,” in the “Author(s)” field they will be able to see the list of all authors fetched from the entries of the “Authors” Content Type. They can select the required author(s) and go ahead with filling data in other fields.

To add a single content type to your Reference field, perform the following steps:

1. Click on the “Settings” gear icon on the Reference field to open its properties.
2. Select Advanced properties.
3. Under the Referenced Content Type dropdown, select the content type that you want to add as a reference.

You can start adding the entry(ies) of the referred content type.

Multiple Content Type Referencing

In Multiple Content Type Referencing, the “Reference” field allows you to create references to entries of multiple content types.

Example: Let’s say you are creating an e-commerce site, and your primary items are “Clothes,” “Shoes,” and “Bags,” and you want to create a page that displays all products of a selected brand.

First, create the content types, “Clothes,” “Shoes,” and “Bags” and create their entries. Then, create the “Brand” content type with the necessary fields and add a “Reference” field named “Products” that refers to all the three content types “Clothes,” “Shoes,” and “Bags.”

Now, whenever content managers create entries for “Brand,” under the “Products” Reference field, they will be able to see the list of all entries from the three referenced content types from which they can select the required product(s) and go ahead with filling data in other fields. If you see the entries of only a single referenced content type, chances are that you have the old Reference field that needs to be updated. For more details, refer to the Upgrade your Reference field page.

To add multiple content types to your Reference field, perform the following steps:

1. Edit a content type and click on the “Settings” gear icon on the Reference field to open its properties.
2. Select the Multiple checkbox under Options in the Advanced properties.
3. Click on the Referenced Content Type dropdown and select the content types that you want to add as references.

You can start adding the entry(ies) of the referred content types.

Note: When selecting content types, at a time you can add 10 content types into a single field. For more limitations, refer to the Limitations section.

Additional Functionalities

Here you can check out what additional functionalities you can perform with the Reference field.

Edit Referenced Entries

After selecting a reference entry from the list of available entries, you can edit the referenced entry in a single click.

To go to the referenced entry page from the Reference field, click on the “Edit” icon that appears beside the referred entry. This will take you to the entry page where you can view or modify the entry as per your requirement.

Warning: Before navigating to the referred entry, make sure to save the parent entry. If the parent entry is not saved, unsaved data may be lost.

Add Multiple References

When you mark a specific Reference field of a content type as Multiple, you will be able to add multiple entries as references in a single field. When entering data for a multiple Reference field, you will see the options: Choose existing entry and Create new entry.

• Choose existing entry - This option will open the Choose entries modal. Select the content type from the Select content type dropdown and choose the entries of the selected content type. Likewise select entries of the other referenced content types as per your requirement, and click on Add selected entries. This will add all the selected entries as a reference in the given reference field.
  
  Depending on the access permissions assigned to you, you will see the “Edit” and the “Delete” icons beside each referenced entry. Clicking on the “Edit” icon will lead you to the entry page where you can make the necessary changes to the entry. The “Delete” icon, will remove an entry from the list of selected referred entries.

• Create new entry

  - You can create and add new reference entries on-the-go. While adding references, if you realize that you need to add a new entry that can be used as a reference, you can do it by clicking the

  Create new entry

  button. After entering the data for the new entry, click on

  Save

  . This will create a new entry for the referred content type and will automatically add it under the Reference field.
  

  Warning: Before navigating to the new entry page, make sure to save the parent entry. If the parent entry is not saved, unsaved data may be lost.

  Then, choose a content type from the Select content type dropdown, and click Create. This opens the add a new entry page where you can enter the data. After entering the data for the new entry, click on Save. This will create a new entry for the referred content type and will automatically add it under the Reference field.

  Note: If a referred child entry is deleted, only the UID of the entry, along with the content type UID, is displayed in the list of referred entries of the Reference field of the parent entry.

Permissions on reference content type

When a content type is referred to in another content type, the type of permissions assigned to the content manager on both these content types play an important role.

Let’s understand this with the help of an example.

Let’s say a content manager needs to create an entry for the “News Article” content type, which has a reference field (named Author) referring to the “Author” content type. In such a scenario, the type of permissions assigned to the content manager on the “Author” content type would define what he can do with the entries of the News Article content type. There are two possibilities.

• No “Read” access on the referenced content type:
  While creating a new entry, if the content manager does not have “read” access to the “Authors” content type, he will not be able to view any data under the “Author” field in the “News Article” content type. Consequently, when such an entry is saved, there would be no data for the “Author” field.
  If the content manager, who does not have “read” access to the “Authors” content type, edits and saves an existing entry, then the value that was previously set for the ‘“Author” field will be wiped out.
• “Read” access but no “Publish” access on the referenced content type:
  If the content manager has “read” access but does not have “publish” access to the “Authors” content type (referenced content type), he will be able to select a value for the “Author” field in the entry, but will not be able to publish the entry.

Additional Resource: Learn how to Use Reference field as Custom Extension.