Usage Examples

This guide provides complete, step-by-step walkthroughs for common use cases of the Primary Entity Reference module.

Overview

Each example includes: - The business scenario - Complete field configuration - Widget selection and setup - Display configuration - What content editors will see - What site visitors will see

Example 1: Product Catalog with Featured Images

Scenario

You're building an e-commerce site. Each product can have multiple images, but you need one marked as the "featured" or "primary" image to display in product listings and search results.

Step-by-Step Setup

Step 1: Add the Field

1. Navigate to Structure → Content types → Product → Manage fields (/admin/structure/types/manage/product/form-display)
2. Click Add field
3. Select Reference → Primary entity reference
4. Label: "Product Images"
5. Click Continue

Step 2: Configure Field Storage

1. Type of item to reference: Media
2. Click Continue

Step 3: Configure Field Settings

1. Required field: Checked (products must have at least one image)
2. Help text: "Upload product images. Mark one as primary—this image will appear in product listings and search results. You can add multiple images for the product gallery."
3. Allowed number of values: Unlimited
4. Media types: Check "Image"
5. Click Save settings

Step 4: Configure the Widget

1. Navigate to Structure → Content types → Product → Manage form display
2. Find "Product Images" in the list
3. In the Widget column, select Autocomplete (for most cases) or Inline entity form - Primary (if you want to upload images directly)
4. Click the gear icon (⚙)
5. For Autocomplete:
   • Placeholder: "Type to search for existing images or upload new ones..."
   • Show primary only: Unchecked
6. Click Update
7. Click Save

Step 5: Configure the Display

For the product listing (Teaser view):

1. Navigate to Structure → Content types → Product → Manage display
2. Select Teaser display mode at the top
3. Find "Product Images"
4. In the Format column, select Rendered entity (Primary Only)
5. Click the gear icon (⚙)
6. View mode: Select a media view mode configured to show images (e.g., "Thumbnail" or "Medium")
7. Click Update
8. In the Label column, select Hidden
9. Click Save

For the full product page (Default view):

1. Select Default display mode at the top
2. You may want to add the field twice:
   • First instance: Use Rendered entity (Primary Only) for the featured image (Label: "Featured Image" or Hidden)
   • Second instance: Use standard Rendered entity formatter with "Multiple" to show all images in a gallery (Label: "Image Gallery" or Hidden)
3. Click Save

What Content Editors See

When creating/editing a product:

1. An autocomplete field labeled "Product Images"
2. They type to search for images or can upload new ones (via Media library)
3. Each added image appears in a list with a radio button
4. They click the radio button next to one image to mark it as primary
5. Help text guides them on the purpose

[Screenshot needed: Product edit form showing multiple images with radio buttons for primary selection]

What Site Visitors See

On product listing pages: - Only the primary/featured image displays for each product

On the full product page: - The primary image displays prominently at the top - All images display below in a gallery - Clicking images opens a larger view

---

Example 2: Blog with Multiple Authors

Scenario

Your blog has articles written by multiple authors. Each article can have several contributing authors, but one should be designated as the primary author who receives the byline.

Step-by-Step Setup

Step 1: Add the Field

1. Navigate to Structure → Content types → Article → Manage fields
2. Click Add field
3. Select Reference → Primary entity reference
4. Label: "Authors"
5. Click Continue

Step 2: Configure Field Storage

1. Type of item to reference: User
2. Click Continue

Step 3: Configure Field Settings

1. Required field: Checked (articles must have an author)
2. Help text: "Select article authors. Mark one as primary—this author will appear as the byline."
3. Allowed number of values: Limited to 5
4. Restrict by role: Check "Editor" and "Administrator" (adjust based on your site's roles)
5. Include blocked users: Unchecked
6. Click Save settings

Step 4: Configure the Widget

1. Navigate to Structure → Content types → Article → Manage form display
2. Find "Authors" in the list
3. In the Widget column, select Autocomplete
4. Click the gear icon (⚙)
5. Match operator: Contains
6. Placeholder: "Type to search for authors..."
7. Show primary only: Unchecked
8. Click Update
9. Click Save

Step 5: Configure the Display

For article listings (Teaser view):

1. Navigate to Structure → Content types → Article → Manage display
2. Select Teaser display mode
3. Find "Authors"
4. In the Format column, select Label (Primary Only)
5. Click the gear icon (⚙)
6. Link label to the referenced entity: Checked (links to author profile)
7. Click Update
8. In the Label column, select Inline
9. Change label text to "By" if desired
10. Click Save

For full article page (Default view):

1. Select Default display mode
2. Configure the primary author display (same as teaser)
3. Optionally add the field again to show all contributing authors below the article
4. Click Save

What Content Editors See

When creating/editing an article:

1. An autocomplete field labeled "Authors"
2. They type author names and select from suggestions
3. Can add up to 5 authors
4. Radio buttons let them mark one as primary
5. The primary author will be featured in the byline

[Screenshot needed: Article edit form with multiple authors and primary selection]

What Site Visitors See

On article listing pages: - "By Jane Smith" (the primary author, linked to their profile)

On the full article page: - Primary author byline at the top - Optionally, "Contributing authors: John Doe, Jane Smith, Alice Johnson" section

---

Example 3: Event with Multiple Locations

Scenario

You're building an event calendar. Some events occur at multiple locations, but you want to designate one as the "primary venue" to display in event listings and maps.

Step-by-Step Setup

Step 1: Create Location Content Type

First, if you haven't already, create a "Location" content type with fields like: - Title (name of location) - Address - Description - Map coordinates (if using a mapping module)

Step 2: Add the Field to Events

1. Navigate to Structure → Content types → Event → Manage fields
2. Click Add field
3. Select Reference → Primary entity reference
4. Label: "Event Locations"
5. Click Continue

Step 3: Configure Field Storage

1. Type of item to reference: Content
2. Click Continue

Step 4: Configure Field Settings

1. Required field: Checked
2. Help text: "Select event locations. Mark one as the primary venue—this location will appear in event listings and on maps."
3. Allowed number of values: Limited to 3 (or Unlimited)
4. Content types: Check only "Location"
5. Sort by: Title - ascending
6. Click Save settings

Step 5: Configure the Widget

Option A: Use Autocomplete (if you have many locations):

1. Navigate to Structure → Content types → Event → Manage form display
2. Find "Event Locations"
3. Widget: Autocomplete
4. Click the gear icon (⚙)
5. Placeholder: "Type to search for locations..."
6. Click Update and Save

Option B: Use Check boxes (if you have < 20 locations):

1. Navigate to Structure → Content types → Event → Manage form display
2. Find "Event Locations"
3. Widget: Check boxes/radio buttons
4. Click Save

Step 6: Configure the Display

For event listings (Teaser view):

1. Navigate to Structure → Content types → Event → Manage display
2. Select Teaser display mode
3. Find "Event Locations"
4. Format: Label (Primary Only)
5. Click the gear icon (⚙)
6. Link label to the referenced entity: Checked
7. Click Update
8. Label: Inline, change to "Location:"
9. Click Save

For full event page (Default view):

1. Select Default display mode
2. Find "Event Locations"
3. Format: Rendered entity (Primary Only)
4. Click the gear icon (⚙)
5. View mode: Full content (or create a custom "Location Details" view mode)
6. Click Update
7. Label: Above, text "Primary Venue"
8. Optionally add the field a second time to show all locations
9. Click Save

What Content Editors See

When creating/editing an event:

1. A field labeled "Event Locations"
2. They search for and add location content
3. Radio buttons let them mark one as primary
4. Help text explains the primary venue will be featured

[Screenshot needed: Event edit form with location selection and primary radio buttons]

What Site Visitors See

On event listing pages: - "Location: Downtown Community Center" (the primary venue, linked)

On the full event page: - "Primary Venue" section with full location details (address, map, etc.) - Optionally, "Additional Locations" section listing other venues

---

Example 4: Company Directory with Multiple Contacts

Scenario

You're creating a company directory. Each company listing can have multiple contact persons, but you want one marked as the "main contact" for initial inquiries.

Step-by-Step Setup

Step 1: Add the Field

1. Navigate to Structure → Content types → Company → Manage fields
2. Click Add field
3. Select Reference → Primary entity reference
4. Label: "Contact Persons"
5. Click Continue

Step 2: Configure Field Storage

1. Type of item to reference: User
2. Click Continue

Step 3: Configure Field Settings

1. Required field: Checked
2. Help text: "Select contact persons for this company. Mark one as the main contact—this person will be listed first and used for primary inquiries."
3. Allowed number of values: Unlimited
4. Restrict by role: Check roles that represent company contacts (e.g., "Company Representative")
5. Click Save settings

Step 4: Configure the Widget

1. Navigate to Structure → Content types → Company → Manage form display
2. Find "Contact Persons"
3. Widget: Autocomplete
4. Click the gear icon (⚙)
5. Placeholder: "Type to search for contact persons..."
6. Click Update and Save

Step 5: Configure the Display

1. Navigate to Structure → Content types → Company → Manage display
2. Find "Contact Persons"
3. Format: Rendered entity (Primary Only)
4. Click the gear icon (⚙)
5. View mode: Create a custom "Contact Card" view mode for users that shows:
   • Name
   • Email
   • Phone
   • Job title (custom field)
6. Click Update
7. Label: Above, text "Main Contact"
8. Add the field a second time below:
   • Format: Label (standard entity reference, showing all)
   • Label: Above, text "Additional Contacts"
9. Click Save

What Content Editors See

When creating/editing a company:

1. Autocomplete field for "Contact Persons"
2. They add multiple contacts
3. Radio buttons mark one as primary/main
4. Clear understanding of who will be the featured contact

[Screenshot needed: Company edit form with multiple contacts and primary selection]

What Site Visitors See

On company directory page: - "Main Contact" section prominently displaying: - Jane Smith - jane.smith@company.com - (555) 123-4567 - Sales Director - "Additional Contacts" section listing other contacts

---

Example 5: Portfolio with Featured Projects

Scenario

You have a portfolio page with multiple project references, but you want one project marked as "featured" to display prominently at the top.

Step-by-Step Setup

Step 1: Add the Field

1. Create a "Portfolio" content type if you haven't already
2. Navigate to Structure → Content types → Portfolio → Manage fields
3. Click Add field
4. Select Reference → Primary entity reference
5. Label: "Featured Projects"
6. Click Continue

Step 2: Configure Field Storage

1. Type of item to reference: Content
2. Click Continue

Step 3: Configure Field Settings

1. Required field: Checked
2. Help text: "Select projects to feature in this portfolio. Mark one as primary—this project will be showcased at the top of the portfolio."
3. Allowed number of values: Limited to 6
4. Content types: Check "Project" (or your project content type)
5. Sort by: Title - ascending
6. Click Save settings

Step 4: Configure the Widget

1. Navigate to Structure → Content types → Portfolio → Manage form display
2. Find "Featured Projects"
3. Widget: Autocomplete
4. Click the gear icon (⚙)
5. Placeholder: "Type to search for projects..."
6. Click Update and Save

Step 5: Configure the Display

1. Navigate to Structure → Content types → Portfolio → Manage display
2. Find "Featured Projects"

3. Add the field twice:

   First instance (Primary featured project): - Format: Rendered entity (Primary Only) - View mode: Full content - Label: Above, text "Featured Project" - Position at the top of the display

   Second instance (Other projects): - Format: Rendered entity (showing all references) - View mode: Teaser - Label: Above, text "More Projects" - Position below the featured project 24. Click Save

What Content Editors See

When creating/editing a portfolio:

1. Autocomplete field to add up to 6 projects
2. Radio buttons to mark one as the featured/primary project
3. Clear indication that the primary will display prominently

[Screenshot needed: Portfolio edit form with project selection]

What Site Visitors See

On the portfolio page: - "Featured Project" section at the top with full project display (large image, complete description, links) - "More Projects" section below with teaser cards for the other projects

---

Example 6: Recipe with Dietary Tags (Using Taxonomy)

Scenario

You're building a recipe site. Each recipe can have multiple dietary tags (vegetarian, vegan, gluten-free, etc.), but you want one marked as the "primary" diet type to use in filtering and badges.

Step-by-Step Setup

Step 1: Create the Taxonomy

1. Navigate to Structure → Taxonomy (/admin/structure/taxonomy)
2. Click Add vocabulary
3. Name: "Dietary Tags"
4. Description: "Tags for dietary restrictions and preferences"
5. Click Save
6. Add terms: Vegetarian, Vegan, Gluten-Free, Dairy-Free, Nut-Free, Paleo, Keto, etc.

Step 2: Add the Field

1. Navigate to Structure → Content types → Recipe → Manage fields
2. Click Add field
3. Select Reference → Primary entity reference
4. Label: "Dietary Tags"
5. Click Continue

Step 3: Configure Field Storage

1. Type of item to reference: Taxonomy term
2. Click Continue

Step 4: Configure Field Settings

1. Required field: Unchecked (not all recipes need dietary tags)
2. Help text: "Select applicable dietary tags. Mark one as primary—this tag will appear as a badge on the recipe."
3. Allowed number of values: Unlimited
4. Vocabularies: Check "Dietary Tags"
5. Create referenced entities if they don't already exist: Checked
6. Click Save settings

Step 5: Configure the Widget

Since you have a small, fixed set of options, use checkboxes:

1. Navigate to Structure → Content types → Recipe → Manage form display
2. Find "Dietary Tags"
3. Widget: Check boxes/radio buttons
4. Click Save

Step 6: Configure the Display

1. Navigate to Structure → Content types → Recipe → Manage display
2. Find "Dietary Tags"
3. Format: Label (Primary Only)
4. Click the gear icon (⚙)
5. Link label to the referenced entity: Checked (links to term page showing all recipes with that tag)
6. Click Update
7. Label: Hidden
8. Position near the recipe title
9. Click Save

What Content Editors See

When creating/editing a recipe:

1. A list of checkboxes for dietary tags
2. Radio buttons next to each checkbox
3. They check applicable tags
4. They mark one as primary for the badge
5. Help text clarifies the primary tag's purpose

[Screenshot needed: Recipe edit form showing checkboxes and radio buttons for dietary tags]

What Site Visitors See

On recipe cards/listings: - A prominent badge (e.g., green "VEGAN" badge) based on the primary tag - Styled to stand out visually

On the full recipe page: - Primary tag displayed as a badge near the title - All tags listed in a "Dietary Information" section

---

Example 7: News Article with Related Media (Inline Entity Form)

Scenario

You're building a news site where articles can embed multiple media items (images, videos, audio clips), but one should be featured as the primary media for the article header.

Step-by-Step Setup

Prerequisites

Ensure the Inline Entity Form module is installed:

composer require drupal/inline_entity_form
drush en inline_entity_form

Step 1: Add the Field

1. Navigate to Structure → Content types → News Article → Manage fields
2. Click Add field
3. Select Reference → Primary entity reference
4. Label: "Article Media"
5. Click Continue

Step 2: Configure Field Storage

1. Type of item to reference: Media
2. Click Continue

Step 3: Configure Field Settings

1. Required field: Checked (articles need at least one media item)
2. Help text: "Add media items for this article. Mark one as primary—this media will appear in the article header."
3. Allowed number of values: Unlimited
4. Media types: Check "Image", "Video", and "Audio"
5. Click Save settings

Step 4: Configure the Widget

1. Navigate to Structure → Content types → News Article → Manage form display
2. Find "Article Media"
3. Widget: Inline entity form - Primary
4. Click the gear icon (⚙)
5. Form mode: Default
6. Allow users to add existing entities: Yes (so editors can reuse media)
7. Allow users to duplicate entities: No
8. Primary label: "Featured Media"
9. Show primary only: Unchecked
10. Click Update and Save

Step 5: Configure the Display

1. Navigate to Structure → Content types → News Article → Manage display
2. Find "Article Media"
3. Format: Rendered entity (Primary Only)
4. Click the gear icon (⚙)
5. View mode: Large (or create a custom "Article Hero" view mode for media)
6. Click Update
7. Label: Hidden
8. Position at the top of the article display
9. Click Save

What Content Editors See

When creating/editing a news article:

1. An inline entity form table showing media items
2. Buttons to "Add new" media or "Add existing" media
3. Each media row has:
4. Radio button for primary selection
5. Edit and Remove buttons
6. Preview of the media
7. They can upload/create media directly within the form
8. They mark one as "Featured Media"

[Screenshot needed: News article edit form with inline entity form showing media table and primary radio buttons]

What Site Visitors See

On the news article page: - The primary/featured media displays prominently in the header (full width image or video player) - Other media may appear embedded in the article body or in a media gallery at the bottom

---

Working with Views

Filtering by Primary Entities in Views

If you want to create a View that only shows primary entities, you can use the following approach:

Example: Creating a "Featured Authors" View

1. Navigate to Structure → Views (/admin/structure/views)
2. Click Add view
3. View name: "Featured Authors"
4. Show: Users
5. Click Continue & edit
6. Add a Relationship:
7. Click Add in the Relationships section
8. Search for your primary entity reference field (e.g., "Content referencing User from field_authors")
9. Check Require this relationship
10. Add a Filter:
11. Click Add in the Filter Criteria section
12. Find "Primary" (from your primary entity reference field)
13. Operator: Is equal to
14. Value: True (or 1)
15. Configure display settings
16. Click Save

This creates a View showing only users who are marked as primary authors in articles.

---

Tips for Success

Planning Your Fields

Before creating a primary entity reference field:

1. Identify the need: Do you genuinely need multiple references with one primary, or would a single reference field suffice?
2. Plan cardinality: How many references should be allowed? Too many can overwhelm editors.
3. Consider the workflow: How will editors use this field? Choose the appropriate widget.
4. Think about display: How will the primary entity display differently from others?

Content Editor Training

When deploying primary entity reference fields:

1. Provide clear help text on every field
2. Use descriptive labels (not just "Primary" but "Featured Image" or "Main Contact")
3. Create editorial guidelines explaining when and how to select the primary entity
4. Offer examples in training materials showing good primary selections

Testing

Always test your configuration:

1. Create sample content with various numbers of references
2. Test the primary selection mechanism with different widgets
3. Verify display in all view modes and contexts
4. Check Views integration if you're using Views
5. Test edge cases like having only one reference, or no primary selected

---

Next Steps

• Configuration Guide - Review field configuration details
• Widgets Guide - Learn more about widget options
• Formatters Guide - Explore display options