Entity Reference Override
Extends Drupal's entity reference field with an accompanying text field that can override aspects of referenced entities such as title, CSS classes, display mode, or field values.
entity_reference_override
Overview
The Entity Reference Override module provides an enhanced entity reference field type that pairs the standard entity reference functionality with a custom text field. This custom text can be used to override specific aspects of the referenced entity when it is displayed on the referencing entity's page.
This is particularly useful for content editors who need context-specific customization of referenced content. For example, when referencing the same author profile from multiple articles, each article can display a different title or bio for that author without modifying the original author entity.
The module supports overriding:
- Entity title/label - completely replace or append to the referenced entity's title
- CSS classes - add custom styling classes to the rendered reference
- Display mode - render the referenced entity in a different view mode
- Text fields - override any string, text, or email field on the referenced entity (experimental)
The override text can be plain text or formatted HTML depending on configuration, making it flexible enough for both simple label overrides and rich content substitution.
Features
- Provides a custom field type 'Entity reference w/custom text' that extends the core entity reference field with additional override and format columns
- Autocomplete widget with inline custom text input field for selecting entities and entering override text simultaneously
- Select dropdown widget for choosing from a list of referenceable entities with accompanying override text field
- Label formatter that displays referenced entity labels with options to replace title, append to title, add suffix after title, or add CSS class to the link
- Rendered entity formatter that displays full entity view with options to override entity title, add CSS class, change display mode, or override any text/string/email field value
- Support for formatted text (HTML) in override field when configured with a text format, enabling WYSIWYG editing for rich content overrides
- Views integration providing both forward relationships (from referencing to referenced entity) and reverse relationships (from referenced to referencing entities)
- Entity Usage module integration for tracking entity relationships through entity_reference_override fields
- Recursive render protection to prevent infinite loops when entities reference each other
- Database schema update hooks for seamless migration from earlier versions with smaller field size limits
Use Cases
Article with custom author bylines
When multiple articles reference the same author profile, each article can display a different byline or title for that author. For example, one article might show 'Dr. Jane Smith, CEO' while another shows 'Jane Smith, Technology Columnist' - all referencing the same author entity.
Product catalog with context-specific descriptions
A product entity referenced from different category pages can display category-specific promotional text or descriptions without duplicating the product entity. The override text replaces or supplements the product's standard description based on context.
Event speakers with session-specific bios
Conference session content can reference speaker profiles while providing session-specific introductions or credentials relevant to each particular talk, rather than using the speaker's generic bio.
Navigation menus with custom link titles
When building navigation that references content entities, use override text to provide menu-specific titles that differ from the content's actual title - useful for shorter menu labels or context-appropriate phrasing.
Featured content blocks with promotional text
A featured content section can reference articles or products while adding promotional or editorial context specific to that placement, such as 'Editor's Pick' badges or custom teaser text.
Related content with relationship context
When showing related content, the override text can explain the relationship: 'See also: Our earlier coverage of this topic' or 'Related: Written by the same author'.
Tips
- Configure the text format setting to NULL for simple overrides like titles or CSS classes to keep the interface clean and avoid unnecessary formatting options
- Use a minimal text format when rich text overrides are needed to prevent complex HTML from breaking layouts
- The override text field supports up to 4094 characters, making it suitable for paragraph-length content overrides
- When overriding CSS classes, ensure the class names don't conflict with existing theme styles
- For the rendered entity formatter, the entity is cloned before modification, so original entities are never affected
- Consider the caching implications when using display mode overrides, as each unique override creates a separate cache entry
- The recursive render protection prevents infinite loops, but avoid creating circular references for performance reasons
Technical Details
Hooks 2
hook_entity_usage_track_info_alter
Integrates with the Entity Usage module to track entity relationships created through entity_reference_override fields. When Entity Usage is enabled, entity_reference_override fields are automatically tracked alongside standard entity_reference fields.
hook_field_views_data
Provides Views integration for entity_reference_override fields, adding both forward and reverse relationships. Forward relationship allows joining from the referencing entity to the referenced entity. Reverse relationship enables filtering and displaying content that references a specific entity.
Troubleshooting 4
The module includes CSS fixes for this issue through the form-fixes library. If problems persist, check for CSS conflicts with your admin theme.
Ensure the override_action setting in the formatter configuration matches the type of override you're attempting. For field overrides, verify the target field exists on the referenced entity's bundle.
Clear the Views cache after adding the field. The relationship should appear under both the referencing entity type and the referenced entity type groups.
The text format must be configured in the field settings (not widget settings). Edit the field configuration and select a text format under 'Custom text format'.
Security Notes 3
- Override text is stored and displayed as configured by the text format setting. When using text formats that allow HTML, ensure appropriate filtering is configured to prevent XSS vulnerabilities.
- The module clones entities before applying overrides, so original entity data is never modified through the override mechanism.
- Field permissions and entity access controls apply normally to both the referencing entity (where the field exists) and the referenced entities.