Mismatched key names: Key names do not always match the labels in the field picker. For example. the key for Title is label, not title.
Nested data structures: The cover image is not a flat value. It is a reference to a media item. Therefore, the data arrives in a nested structure. The image resides one level further down, under the image field of the media item.
To understand both concepts, review the following three rules.
Three rules determine the keys in the delivered JavaScript object.
Content identifiers: A field with a defined role, such as a title or an author, receives a new name.
Property output formats: A single property provides a string value. Multiple properties provide an object.
Nested references: A field on referenced content nests under the parent reference key.
Content identifiers: A field that identifies the content receives a new name
Some fields have a defined role for the content type, such as the title or the author. Those fields arrive under the role name rather than the field name. For Content, the fields map as follows:
Dialog box selection
Key in the prop value
Title
label
ID
id
Revision ID
revision
Content type
bundle
Published
published
Authored by
owner
Other content entity types follow the same rule. The Name of a media item also arrives as label. The cover_image.label property in the previous example demonstrates this behavior. The Name of a taxonomy term follows the same pattern.
Every other field keeps its original name. Body arrives as body, Cover Image as cover_image, and the Image of the media item as media_image.
Important
To confirm the exact key of a field, inspect the value. Do not guess.
Property output formats: One property provides a value. Several properties provide an object.
To produce body as a string, select only Body → Processed text.
To produce the image field as an object with the selected properties as keys, select both ImageURL and Alternative text on an image field:
When you select a field on referenced content, the system nests it under the key of the field that points to it. The nested object carries its own __type.
Images typically arrive in this format. A Cover Image field does not hold an image directly. It references a media item. Therefore, when you select the Image → Image URL of the media item, the system produces:
The same rule applies to any reference. When you select Author profile → Title, it produces author_profile: { __type: "person", label: "Ada Lovelace" }.
Select only single-value fields
A field that holds more than one value does not appear in the Content Relationship dialog box. The fields of the referenced content also do not appear. On an Article, fields such as Tags, Categories, and Related articles hold many values. Therefore, they do not appear in the list.
If an expected field does not appear, verify if the field configuration holds more than one value.
Every object carries __type
Each object at the top level and at every nested level includes a __type key. This key identifies the content type it represents. Use it when you must branch on the content type. Treat it as reserved.
Handle missing values
Two independent elements can be missing. A robust component checks both elements.
The entire prop can benull. This occurs when no content is referenced, when the referenced content is deleted, or when a content template maps an empty reference field. Never assume that the object exists.
An individual field can benull. An article with no cover image yields cover_image: null instead of an object with empty values. A field can also change shape or disappear if the content type configuration changes later.
Nested structures compound this behavior. To reach an image, you must pass through the reference, the media item, and the image field. Any of these elements can be missing.
Because the interface does not display key names, confirm them when you render the value. Temporarily replace the output of the component with the value itself:
Reference a piece of content in the field of the prop.
Read the resolved object in the page preview.
The preview displays exactly what your code receives. This includes __type, the renamed keys, and any nested structures. Restore the real output of your component after you finish.
Perform this action whenever you add or change a field selection. Ensure that you do this before you write code against a field that you added to the content type.
Print the value from a terminal
If you work with a local codebase, print the resolved value. With this approach, you do not need to place the component on a page. This method is faster than the page preview when you iterate on a field selection.
The command reads the component from your local project and requests the site to resolve the fields against a real piece of content. Therefore, a component that you author in the browser remains invisible to the command until you pull the component to your local environment.
To print the resolved value from a local codebase:
The output is the same object that your code receives. This includes __type, the renamed keys, and any nested structures.
If the command reports that the component is missing, it searches in your local project instead of the site. Run the npx canvas pull command first.
Information absent from the code editor preview
The Preview pane inside the code editor does not resolve content entity reference props. The pane has no selected content. Therefore, the prop arrives as an empty string instead of an object or a null value.
This behavior has two consequences:
You cannot use the preview of the code editor to discover the shape of the value. Use the page preview instead, as described previously.
Code that assumes the prop is either an object or null might render differently in the preview of the code editor than it does on a page. Do not treat the preview of the code editor as a test for your null handling.
Content hidden from the viewer
The system resolves field values against the permissions of the person who views the page. The system checks permissions for every piece of content that the prop reaches. This includes content reached when you follow a reference.
If a viewer does not have permission to view the referenced content, the component does not silently omit the field. Instead, the page fails to render that component. This behavior is critical when you follow a reference into non-public content, such as the account of the author who created an article. Select fields from referenced content only when every viewer has permission to view that content.
Reference content to tie the component to the content type
When you select fields, Drupal Canvas records the content type and those specific fields as component requirements. A component that reads the body and image of an article requires a site where the Article type contains those fields with the exact configuration.
The practical effects include:
The component might not be reusable on another site with different content types.
If an administrator removes or reconfigures a field that the component reads, the output of the component changes or the field arrives as null.
Select only the required fields.
Consuming a content entity reference prop
This developer focused guide provides instructions for developers who write the code for a component that has a Content entity reference prop.
Note
As Drupal Canvas does not display the data structure of the prop, ensure that you understand it precisely.
The value is an object
A content entity reference prop delivers a plain JavaScript object. This object contains only the selected fields.
For example, a prop named article targets Content → Article.
Mismatched key names: Key names do not always match the labels in the field picker. For example. the key for Title is label, not title.
Nested data structures: The cover image is not a flat value. It is a reference to a media item. Therefore, the data arrives in a nested structure. The image resides one level further down, under the image field of the media item.
To understand both concepts, review the following three rules.
Three rules determine the keys in the delivered JavaScript object.
Content identifiers: A field with a defined role, such as a title or an author, receives a new name.
Property output formats: A single property provides a string value. Multiple properties provide an object.
Nested references: A field on referenced content nests under the parent reference key.
Content identifiers: A field that identifies the content receives a new name
Some fields have a defined role for the content type, such as the title or the author. Those fields arrive under the role name rather than the field name. For Content, the fields map as follows:
Dialog box selection
Key in the prop value
Title
label
ID
id
Revision ID
revision
Content type
bundle
Published
published
Authored by
owner
Other content entity types follow the same rule. The Name of a media item also arrives as label. The cover_image.label property in the previous example demonstrates this behavior. The Name of a taxonomy term follows the same pattern.
Every other field keeps its original name. Body arrives as body, Cover Image as cover_image, and the Image of the media item as media_image.
Important
To confirm the exact key of a field, inspect the value. Do not guess.
Property output formats: One property provides a value. Several properties provide an object.
To produce body as a string, select only Body → Processed text.
To produce the image field as an object with the selected properties as keys, select both ImageURL and Alternative text on an image field:
When you select a field on referenced content, the system nests it under the key of the field that points to it. The nested object carries its own __type.
Images typically arrive in this format. A Cover Image field does not hold an image directly. It references a media item. Therefore, when you select the Image → Image URL of the media item, the system produces:
The same rule applies to any reference. When you select Author profile → Title, it produces author_profile: { __type: "person", label: "Ada Lovelace" }.
Select only single-value fields
A field that holds more than one value does not appear in the Content Relationship dialog box. The fields of the referenced content also do not appear. On an Article, fields such as Tags, Categories, and Related articles hold many values. Therefore, they do not appear in the list.
If an expected field does not appear, verify if the field configuration holds more than one value.
Every object carries __type
Each object at the top level and at every nested level includes a __type key. This key identifies the content type it represents. Use it when you must branch on the content type. Treat it as reserved.
Handle missing values
Two independent elements can be missing. A robust component checks both elements.
The entire prop can benull. This occurs when no content is referenced, when the referenced content is deleted, or when a content template maps an empty reference field. Never assume that the object exists.
An individual field can benull. An article with no cover image yields cover_image: null instead of an object with empty values. A field can also change shape or disappear if the content type configuration changes later.
Nested structures compound this behavior. To reach an image, you must pass through the reference, the media item, and the image field. Any of these elements can be missing.
Because the interface does not display key names, confirm them when you render the value. Temporarily replace the output of the component with the value itself:
Reference a piece of content in the field of the prop.
Read the resolved object in the page preview.
The preview displays exactly what your code receives. This includes __type, the renamed keys, and any nested structures. Restore the real output of your component after you finish.
Perform this action whenever you add or change a field selection. Ensure that you do this before you write code against a field that you added to the content type.
Print the value from a terminal
If you work with a local codebase, print the resolved value. With this approach, you do not need to place the component on a page. This method is faster than the page preview when you iterate on a field selection.
The command reads the component from your local project and requests the site to resolve the fields against a real piece of content. Therefore, a component that you author in the browser remains invisible to the command until you pull the component to your local environment.
To print the resolved value from a local codebase:
The output is the same object that your code receives. This includes __type, the renamed keys, and any nested structures.
If the command reports that the component is missing, it searches in your local project instead of the site. Run the npx canvas pull command first.
Information absent from the code editor preview
The Preview pane inside the code editor does not resolve content entity reference props. The pane has no selected content. Therefore, the prop arrives as an empty string instead of an object or a null value.
This behavior has two consequences:
You cannot use the preview of the code editor to discover the shape of the value. Use the page preview instead, as described previously.
Code that assumes the prop is either an object or null might render differently in the preview of the code editor than it does on a page. Do not treat the preview of the code editor as a test for your null handling.
Content hidden from the viewer
The system resolves field values against the permissions of the person who views the page. The system checks permissions for every piece of content that the prop reaches. This includes content reached when you follow a reference.
If a viewer does not have permission to view the referenced content, the component does not silently omit the field. Instead, the page fails to render that component. This behavior is critical when you follow a reference into non-public content, such as the account of the author who created an article. Select fields from referenced content only when every viewer has permission to view that content.
Reference content to tie the component to the content type
When you select fields, Drupal Canvas records the content type and those specific fields as component requirements. A component that reads the body and image of an article requires a site where the Article type contains those fields with the exact configuration.
The practical effects include:
The component might not be reusable on another site with different content types.
If an administrator removes or reconfigures a field that the component reads, the output of the component changes or the field arrives as null.
Select only the required fields.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.