Skip to content

Formatter Configuration Guide

This guide explains how to display Primary Entity Reference fields using the available formatters.

Overview

Formatters control how the field appears to site visitors when they view content. The Primary Entity Reference module provides three formatters, each designed to display only the primary entity in different ways.

Key Concept: Primary-Only Display

Important: All three formatters display only the primary entity. Non-primary entities are not shown. If you need to display all referenced entities, use the standard entity reference formatters instead.

Selecting a Formatter

To choose and configure a formatter:

  1. Go to Structure → Content types → [Your content type] → Manage display (/admin/structure/types/manage/[type]/display)
  2. You may need to select a display mode (Default, Teaser, Full content, etc.)
  3. Find your primary entity reference field in the list
  4. In the Format column dropdown, select one of these options:
  5. Label (Primary Only)
  6. Entity ID (Primary Only)
  7. Rendered entity (Primary Only)
  8. Click Save to apply the formatter
  9. Click the gear icon (⚙) to configure formatter-specific settings

Formatter Types

1. Label (Primary Only)

Displays: The label/name of the primary referenced entity, optionally as a link.

How It Works

  • Shows the entity's title, name, or label (the human-readable identifier)
  • Can link to the referenced entity
  • Clean, simple text output
  • Most common formatter for entity references

When to Use

  • You only need to display the entity's name
  • You want a clickable link to the referenced entity
  • Space is limited (e.g., in a compact teaser view)
  • You're showing the reference in a list or table

Configuration Options

Click the gear icon (⚙) to access settings:

Link label to the referenced entity: - Checked: The label becomes a clickable link to the entity - Unchecked: Plain text label with no link - Default: Checked

Output Examples

With link:

<a href="/node/123">John Smith</a>

Without link:

John Smith

Example Setup: Article Primary Author

Field: Authors (User reference)
Formatter: Label (Primary Only)
Settings:
  - Link label to the referenced entity: Checked
Display mode: Default

Result: Displays "John Smith" as a link to the user profile.

2. Entity ID (Primary Only)

Displays: The numeric entity ID of the primary referenced entity.

How It Works

  • Shows the entity's internal ID number
  • Plain numeric output
  • No link, just the raw ID
  • Rarely used for public-facing pages

When to Use

  • Debugging or development purposes
  • Administrative displays
  • When you need the ID for custom theming or JavaScript
  • Integration with external systems that need entity IDs

Configuration Options

This formatter has no configurable settings—it simply displays the entity ID.

Output Example

123

Example Setup: Product ID Reference

Field: Related Products (Content reference)
Formatter: Entity ID (Primary Only)
Display mode: Admin view

Result: Displays "456" (the node ID of the primary product).

3. Rendered entity (Primary Only)

Displays: The full rendered output of the primary entity in a specific view mode.

How It Works

  • Renders the complete entity using its configured display settings
  • You choose which view mode to use (Default, Teaser, Full content, etc.)
  • Can include all fields, images, and formatting from that entity
  • Most powerful but potentially slowest formatter

When to Use

  • You want to embed the full entity display
  • You need to show multiple fields from the referenced entity
  • You want consistent presentation using existing view modes
  • You're creating rich content displays

Configuration Options

Click the gear icon (⚙) to access settings:

View mode: - Select which display mode to use when rendering the entity - Options depend on the entity type being referenced - Common options: Default, Teaser, Full content - Each view mode has its own field configuration

Link label to the referenced entity: - Checked: Wraps the rendered entity in a link to itself - Unchecked: Renders entity without a surrounding link - Default: Checked (varies by entity type)

Output Example

Renders the complete entity output, which might include:

<article>
  <h2><a href="/node/123">Article Title</a></h2>
  <img src="/files/image.jpg" alt="Featured image">
  <div class="summary">Article summary text...</div>
  <a href="/node/123">Read more</a>
</article>

Field: Featured Product (Content reference)
Formatter: Rendered entity (Primary Only)
Settings:
  - View mode: Teaser
  - Link label to the referenced entity: Checked
Display mode: Default

Result: Displays the primary product using the product's "Teaser" view mode configuration.

Formatter Comparison

Feature Label Entity ID Rendered Entity
Shows entity name/title ✅ Yes ❌ No ✅ Yes (in view mode)
Can link to entity ✅ Yes ❌ No ✅ Yes
Shows multiple fields ❌ No ❌ No ✅ Yes
Performance impact ✅ Fast ✅ Fastest ⚠️ Can be slow
Best for simple displays ✅ Yes ➖ Rarely used ❌ No (overkill)
Best for rich displays ❌ No ❌ No ✅ Yes
Customization needed ❌ Minimal ❌ None ✅ Via view modes

Common Formatting Scenarios

Scenario 1: Display Primary Author Name

Goal: Show the primary author's name as a link to their profile.

Configuration:

Formatter: Label (Primary Only)
Settings:
  - Link label to the referenced entity: Checked

Output: "Jane Doe" (linked to /user/45)

Scenario 2: Display Primary Image

Goal: Show the primary product image with image styles applied.

Configuration:

Formatter: Rendered entity (Primary Only)
Settings:
  - View mode: Thumbnail (or create custom "Product Image" view mode)

Note: Configure the Media type's "Thumbnail" view mode to show the image field with desired image style.

Output: Rendered image with configured image style applied.

Scenario 3: Display Featured Article Teaser

Goal: Show a full teaser of the primary related article.

Configuration:

Formatter: Rendered entity (Primary Only)
Settings:
  - View mode: Teaser
  - Link label to the referenced entity: Checked

Output: Complete article teaser with title, image, summary, and "Read more" link.

Scenario 4: Display Primary Location Details

Goal: Show all details of the primary event location.

Configuration:

Formatter: Rendered entity (Primary Only)
Settings:
  - View mode: Full content (or custom "Location Details" view mode)

Output: Complete location node with address, map, hours, contact info, etc.

Working with View Modes

When using the Rendered entity (Primary Only) formatter, you leverage Drupal's view mode system.

Understanding View Modes

View modes are predefined display configurations for entities. Each view mode has its own field display settings.

Common view modes: - Default: Full display, typically used on the entity's main page - Teaser: Abbreviated display, often used in lists - Full content: Complete display with all details

Configuring View Modes

To customize how an entity appears when rendered:

  1. Navigate to Structure → [Entity type] → Manage display (e.g., Structure → Content types → Article → Manage display)
  2. Select the view mode you're using (or create a custom one)
  3. Configure which fields to show and how to display them
  4. Save the display configuration

Example: Configure the "Teaser" view mode for products to show image, title, price, and "Add to cart" button.

Creating Custom View Modes

For more control, create custom view modes:

  1. Go to Structure → Display modes → View modes (/admin/structure/display-modes/view)
  2. Select the entity type (e.g., "Content")
  3. Click Add view mode
  4. Enter a name (e.g., "Featured Product")
  5. Save
  6. Go to your entity's Manage display page
  7. Click Custom display settings tab
  8. Enable your new view mode
  9. Configure the new view mode's field display

Multiple Display Modes

You can configure different formatters for different display modes on your content type:

Example: Article Content Type with Related Articles Field

  • Default (full page view): Use "Rendered entity (Primary Only)" with "Teaser" view mode
  • Teaser (in listings): Use "Label (Primary Only)" with link
  • Search index: Use "Label (Primary Only)" without link

To configure:

  1. Go to Manage display
  2. Select Default display mode at the top
  3. Configure the formatter
  4. Click Save
  5. Select Teaser display mode
  6. Configure a different formatter
  7. Click Save

Hiding the Field

To hide the field in a specific display mode:

  1. Go to Manage display for that display mode
  2. Find your field in the list
  3. In the Format column, select < Hidden >
  4. Click Save

The field will not appear in that display mode.

Advanced: Showing Both Primary and All References

If you need to show the primary entity separately AND all entities together:

  1. Add the field twice to the display:
  2. In Manage display, click the + Add field button in the "Disabled" section
  3. Drag your primary entity reference field into the active area a second time
  4. Configure one instance with a primary-only formatter
  5. Configure the other with a standard entity reference formatter
  6. Use field labels to distinguish them (e.g., "Featured Image" vs. "All Images")

Performance Considerations

Label Formatter

  • Fast: Simple database query for entity label
  • Use freely in lists and views

Entity ID Formatter

  • Fastest: No additional queries needed
  • Minimal performance impact

Rendered Entity Formatter

  • Slower: Fully loads and renders the referenced entity
  • Each rendered entity can trigger additional queries for its fields
  • Be cautious using in lists with many items
  • Consider caching strategies for high-traffic pages

Tip: For better performance, use simpler view modes (like "Teaser") rather than "Full content" when using the Rendered entity formatter.

Field Label Display

Control whether the field label appears:

  1. In Manage display, find your field
  2. In the Label column, select:
  3. Above: Label appears above the field value
  4. Inline: Label appears inline with value
  5. Hidden: No label, just the value
  6. Visually Hidden: Label hidden from screen but available to screen readers

Common choices: - Use Hidden for primary images (the image speaks for itself) - Use Above for labeled sections like "Featured Author" - Use Inline for compact displays like "Primary contact: John Smith"

Best Practices

Choose the Simplest Formatter

Use the simplest formatter that meets your needs: - Need just a name? → Use Label formatter - Need full entity display? → Use Rendered entity formatter - Don't use Rendered entity when Label would suffice

Consider Mobile Display

The Rendered entity formatter can produce large output. Test on mobile: - Use responsive view modes - Consider using Label formatter for mobile display mode

Use Caching

When using Rendered entity formatter: - Enable Drupal's page cache and dynamic page cache - Consider using a CDN for high-traffic pages - Use Views caching if displaying in a View

Provide Context

When using Label formatter alone, consider providing context: - Use field labels: "Primary Author: John Smith" - Or add prefix text in custom templates

Next Steps