Inline Entity Form
Provides widgets for inline management (creation, modification, removal) of referenced entities within parent entity forms.
inline_entity_form
Overview
Inline Entity Form is a powerful Drupal module that enables inline management of referenced entities directly within parent entity forms. The primary use case is parent-child relationships (such as product display → products, order → line items, or node → referenced content) where child entities are primarily managed within the context of their parent, rather than through separate forms.
The module provides two field widgets that can be used with entity_reference and entity_reference_revisions field types. The Simple widget displays an embedded entity form in a fieldset, suitable for single-value required fields with one target bundle. The Complex widget offers a comprehensive table-based interface with buttons for adding, editing, removing, duplicating, and reordering referenced entities.
Key capabilities include: creating new referenced entities inline, editing existing entities without leaving the parent form, referencing existing entities via autocomplete, configurable entity deletion behavior when references are removed, drag-and-drop reordering of multi-value references, collapsible form containers, custom form mode support for different entity form layouts, automatic revision creation for revisionable entities, and full multilingual/translation support.
The module is highly extensible through a handler-based architecture. It automatically registers an inline form handler for all entity types, with specialized handling for nodes. Developers can create custom handlers for specific entity types by implementing the InlineFormInterface. Several hooks allow modules and themes to alter entity forms, reference forms, and table field displays.
Features
- Provides two field widgets: Simple (single-value) and Complex (multi-value) for inline entity management
- Supports entity_reference and entity_reference_revisions field types
- Create new referenced entities directly within the parent entity form without navigating away
- Edit existing referenced entities inline with full form support
- Add existing entities via autocomplete search with configurable matching (STARTS_WITH or CONTAINS)
- Duplicate existing referenced entities with one click
- Remove entity references with configurable deletion behavior (keep always, delete always, or let user decide)
- Drag-and-drop reordering of multiple referenced entities using tabledrag
- Collapsible and expandable form containers to reduce visual clutter
- Custom form mode support allowing different form displays for inline vs standalone editing
- Automatic revision creation when configured for revisionable entity types
- Full multilingual support with automatic translation handling for inline entities
- Handler-based architecture allowing custom inline form handlers per entity type
- Specialized node inline form handler with published/unpublished status display
- Drupal 7 to Drupal 8+ migration support with automatic widget type mapping
- Extensible table display with support for label, field, and callback column types
- Hook system for altering entity forms, reference forms, and table fields
Use Cases
Product Display with Product Variations (Commerce)
In Drupal Commerce, product displays contain product variations (different sizes, colors, etc.). Using IEF Complex widget on the product reference field allows store managers to create and edit all variations directly on the product display form. Each variation can have its own price, SKU, and attributes, all managed inline without navigating to separate forms.
Order Line Items Management
E-commerce orders contain multiple line items. The IEF Complex widget enables order administrators to add, edit, or remove line items directly on the order form. This is particularly useful for phone orders or manual adjustments where the full line item form needs to be accessible.
Article with Embedded Media
A content type 'Article' has an entity reference field to 'Media' entities. Using IEF Simple widget, editors can create or edit the associated media item directly within the article form. The collapsible option keeps the form clean while still providing full media editing capabilities.
Parent-Child Content Relationships
When building hierarchical content structures (like a Course containing Lessons), IEF Complex widget on the Lessons field allows content editors to manage all lessons within the course form. Drag-and-drop reordering ensures lessons can be sequenced properly.
Paragraphs-style Content Building
While the Paragraphs module has its own widget, IEF can be used with entity_reference_revisions fields to create similar paragraph-like content building experiences. Each paragraph type gets its own inline form, and content can be reordered and managed within the parent.
Node Translation with Inline Entities
When translating a node that contains inline entities, IEF automatically handles the translation workflow. If the parent is being translated to French, the inline entity forms will show the French translation (creating it if needed) while respecting field translatability settings.
Tips
- For the Simple widget, ensure the entity reference field is configured with exactly one target bundle for best results
- Use the 'Let the user decide' option for removed_reference when entities might be referenced elsewhere
- Create dedicated form modes for inline editing to show only essential fields and reduce form complexity
- When using nested IEFs (inline entities that themselves have inline entity fields), ensure the parent entity type/bundle differs from child to prevent recursion
- The Complex widget works best with tabledrag for reordering, but tabledrag is automatically disabled when a row form is open
- Consider using the collapsible option for large inline forms to improve the parent form's usability
- The allow_existing option is powerful but can impact performance on large sites - use STARTS_WITH matching for better performance
- Hook into hook_inline_entity_form_table_fields_alter to add custom columns like inventory status, pricing, or other relevant data to the entity table
Technical Details
Hooks 3
hook_inline_entity_form_entity_form_alter
Allows modules and themes to alter the entity form before it is included in the IEF widget. Can be used to modify form elements, add validation, change field visibility, or add custom processing.
hook_inline_entity_form_reference_form_alter
Allows modules and themes to alter the reference form (autocomplete form for adding existing entities) before it is included in the IEF widget. Useful for customizing the autocomplete field or adding additional fields.
hook_inline_entity_form_table_fields_alter
Allows modules to alter the fields displayed in the IEF entity table. Can add new columns, remove existing ones, or modify column settings. Supports label, field, and callback column types.
Troubleshooting 6
Ensure the entity type has an inline form handler. Check that the widget is properly selected in the form display settings. Verify the user has permission to create/edit the target entity type.
Check that entities of the target type/bundle exist and are accessible. Verify the selection handler settings on the field allow the expected entities. Check if view permissions are properly configured.
Ensure the #save_entity property is TRUE (default) on the inline_entity_form element. Check for validation errors in the inline form that may be preventing submission.
Verify the target entity type has translation enabled. Check that the language field is configured for translation. Ensure content_translation module is enabled for the entity type.
This is expected behavior - duplicate creates a copy with the same field values. The duplicate will get a new ID when saved. You may need to clear certain fields after duplication using hook_inline_entity_form_entity_form_alter.
Check the removed_reference setting and entity access permissions. If set to 'Delete always', users need delete permission. Also verify the field is not required with no way to add replacement entities.
Security Notes 4
- Entity access is respected - users can only create, edit, or delete entities they have permission for
- The autocomplete for 'Add existing' entities respects view access and selection handler restrictions
- When removed_reference is set to 'delete', verify users should have implicit delete permission through the widget
- Form token validation prevents CSRF attacks on inline form submissions