This document provides instructions for configuring content entity reference props. Content entity reference props enable a code component to display live data from an existing piece of content. A content author selects the content to reference, and the component receives the fields selected during the build process. When the referenced content changes, the component reflects the change without data re-entry.

Use a content entity reference prop when a component must present content that already exists on the site, such as a card for an article, a liftup for a product, or a related-content teaser. Unlike a text prop, the value does not copy into the component. It stays connected to the source content.

Prerequisites

• Access to Drupal Canvas with permission to create and edit code components. For more information, visit Managing permissions
• At least one content type, media type, taxonomy vocabulary, or other content entity bundle to reference.
• The fields to display on the component must already exist on that bundle.

Understanding content entity reference props

A content entity reference prop has two parts:

• Allowed type: The single entity type and bundle a content author is permitted to link to. 
  • For example, Content restricted to the Article bundle. 
• Entity fields: The specific fields and field properties of that bundle the component receives. 
  • Examples include the title, the processed text of the body, the image URL, and alternative text.

Select both parts to define the prop. The content author only selects which entity to link to. This separation keeps the data contract of the component stable while it provides authors full control over curation.

Adding a content entity reference prop

1. Access your site.
2. On the top right, click Edit to open Drupal Canvas.
3. In the left toolbar, click the Code </> icon to open the code-based components menu.

4. Select the code component to edit.

   The system opens the Preview and Component data panels for the component.

5. In the Component data pane, on the Props tab, click + Add. For more information, visit Props.
6. Enter a Prop name.
7. From the Type list, select Content entity reference.

8. Select Add type. 

   The Content Relationship dialog box opens.

9. Select an entity type from the Select entity type list.
10. Select a bundle from the Select bundle list.

11. Click Continue.

    The dialog box lists every field on that bundle.

12. Select the checkbox for each field or field property the component needs. To reach the properties of a field, expand the field. 

    For example, expand Body to select Processed text.

13. Select Save.

The prop displays the entity type, the bundle, and an Entity fields count.

14. (Optional): 
    1. Click Expand fields to review the selected fields.
    2. Click Edit to change the selection.

Selecting fields and following references

The Content Relationship dialog box categorizes fields into three groups:

For example: Images are commonly reference fields. A Cover Image field points to a media item and does not contain an image directly. 

To reach the image in this example:

1. Add a content entity reference prop.
2. Expand Cover Image.
3. Expand the Image field of the media item.
4. Select Image URL and Alternative text.
5. To produce a nested object in the prop value, select fields on referenced content.

Excluded multi-value fields

The dialog box displays only fields that hold a single value. A reference follows only to a single-value field. Fields such as Tags, Categories, and Related articles hold many values. Therefore, these fields do not appear in the dialog box.

Constraints

Content entity reference props behave differently from other prop types. The Props tab reflects this behavior and hides controls that do not apply.

Referencing the entity as a content author

After the component is placed on a page, the prop displays as an autocomplete field labeled with the title of the prop. Enter part of the content title to search, then select a result. Authors can select only content of the configured entity type and bundle.

In a content template, connect a content entity reference prop to structured data instead of a manually selected entity:

• Entity reference field: Connect the prop to an entity reference field on the template entity. For example, a Related articles field on an Article template can populate the prop of an Article card component.
• Template host entity: Connect the prop to the host entity of the template when the prop targets the same entity type and bundle as the template itself. For example, an Article template can pass its own article into an Article card component.

Verifying the result

Place the component on a page, reference an entity, and confirm the component renders the data of that entity. Change a field on the referenced entity and reload the page. The component reflects the new value, because the data resolves at render time instead of at the time of creation.

Content entity reference props