Skip to content

Field Configuration Guide

This guide explains how to add and configure a Primary Entity Reference field on your content types.

Overview

Primary Entity Reference fields are configured in two stages:

  1. Field Storage Settings: Define what type of entity can be referenced (applies to all content types using this field)
  2. Field Settings: Configure options specific to this content type (target bundles, required status, etc.)

Adding a Primary Entity Reference Field

Step 1: Navigate to Field Management

  1. Go to Structure → Content types (/admin/structure/types)
  2. Find your content type and click Manage fields
  3. Click the Add field button

Step 2: Select Field Type

  1. Under Add a new field, look in the dropdown menu
  2. Find Reference → Primary entity reference
  3. Enter a descriptive Label (e.g., "Product Images", "Authors", "Related Locations")
  4. The Machine name will auto-generate (you can customize it if needed)
  5. Click Continue

Step 3: Configure Field Storage Settings

These settings apply to the field across all content types that use it.

Target Type

Choose which type of entity can be referenced:

  • Content (nodes) - Reference other content pages
  • Taxonomy term - Reference terms from vocabularies
  • User - Reference user accounts
  • Media - Reference media items (images, videos, etc.)
  • File - Reference files
  • Custom entity types - Any custom entities available on your site

Example: For a product image field, select Media. For an author field, select User.

Click Continue to proceed to field settings.

Step 4: Configure Field Settings

These settings apply only to this specific instance of the field.

Required Field

  • Check Required field if content editors must select at least one entity
  • Leave unchecked if the field is optional

Help Text

Enter instructions to help content editors understand how to use the field.

Example: "Select product images and mark one as the primary image to display in listings."

Default Value

Optionally set a default referenced entity that will be pre-selected when creating new content.

Allowed Number of Values

Choose how many entities can be referenced:

  • Limited - Set a specific maximum number (e.g., 1, 5, 10)
  • Unlimited - Allow any number of references

Important: For the primary concept to make sense, you typically want to allow multiple values. However, the field can work with a single value if needed.

Reference Type Settings

Depending on the entity type selected, you'll see additional options:

For Content (Node) References
  • Content types: Select which content types can be referenced
  • Sort by: Choose how to sort available content in widgets
  • Include unpublished content: Allow referencing unpublished content (use with caution)
For Taxonomy Term References
  • Vocabularies: Select which vocabularies' terms can be referenced
  • Create referenced entities if they don't exist: Allow creating new terms from the autocomplete widget
For Media References
  • Media types: Select which media types can be referenced (images, videos, documents, etc.)
  • Sort by: Choose default sorting
For User References
  • Restrict by role: Optionally limit to specific user roles
  • Include blocked users: Allow referencing blocked users (typically unchecked)

Step 5: Save Field Configuration

Click Save settings to create the field.

Common Configuration Scenarios

Scenario 1: Product with Multiple Images

Goal: Allow multiple product images with one marked as primary.

Configuration: - Target type: Media - Media types: Image - Allowed number of values: Unlimited (or a specific limit like 10) - Required: Yes - Help text: "Upload product images. Select at least one image and mark the primary image to show in catalog listings."

Scenario 2: Article with Multiple Authors

Goal: Reference multiple authors but designate one as primary.

Configuration: - Target type: User - Restrict by role: Author, Editor - Allowed number of values: Limited to 5 - Required: Yes - Help text: "Select article authors. Mark one author as primary to display as the byline."

Scenario 3: Event with Multiple Locations

Goal: List multiple event locations with one marked as the primary venue.

Configuration: - Target type: Content - Content types: Location - Allowed number of values: Unlimited - Required: Yes - Help text: "Select event locations. Mark one location as the primary venue to feature in event details."

Scenario 4: Blog Post with Related Content

Goal: Reference related blog posts with one as the featured recommendation.

Configuration: - Target type: Content - Content types: Blog post - Allowed number of values: Limited to 3 - Required: No - Help text: "Optionally select up to 3 related posts. Mark one as primary to feature prominently."

Editing Field Configuration

To modify field settings after creation:

  1. Go to Structure → Content types → [Your content type] → Manage fields
  2. Find your primary entity reference field
  3. Click Edit in the Operations column
  4. Modify settings as needed
  5. Click Save settings

Note: Some storage settings (like target type) cannot be changed after creation. You'll need to delete the field and create a new one if you need to change these.

Field Settings vs. Widget Settings

It's important to understand the difference:

  • Field settings (covered on this page) control what can be stored and basic validation
  • Widget settings (covered in Widgets Guide) control how content editors interact with the field
  • Display settings (covered in Formatters Guide) control how the field appears to site visitors

Best Practices

Naming Conventions

Use clear, descriptive field labels that indicate the field accepts multiple values:

  • ✅ Good: "Product Images", "Authors", "Event Locations"
  • ❌ Avoid: "Image", "Author", "Location"

Help Text

Always provide clear help text that explains: 1. What should be referenced 2. How many items to select 3. What marking an item as "primary" means

Example: "Select product images. Mark one as primary—this image will appear in product listings and search results."

Cardinality

Consider carefully how many values to allow:

  • Unlimited: Most flexible but can lead to overwhelming UI
  • Limited: Provides clear boundaries for content editors
  • Single value: Primary flag still works but provides less value

Target Bundles

Only allow entity bundles that make sense for your use case:

  • For a "Related Articles" field, don't allow referencing "Page" or "Product" content types
  • For a "Product Images" field, only allow "Image" media type

This reduces confusion and prevents errors.

Next Steps