ICT:D Linking Assets to Person

Drupal: Linking Assets to Persons (MM Relationship Without Custom Code)

Purpose

This page documents the step‑by‑step implementation of a **many‑to‑many–style relationship between Person and Asset entities** in Drupal 11.x.

The objective is to allow editors to:

• link existing Assets to a Person,
• manage these links in a table‑based UI,
• search and select Assets via a modal browser,
• avoid custom modules and custom database tables.

This solution uses **standard Drupal mechanisms** and is upgrade‑safe.

---

Design Principles

• Prefer configuration over code
• Avoid custom schema and join tables
• Use Drupal’s entity reference system
• Use contrib modules for UX, not data modeling
• Ensure maintainability and handover safety

---

Conceptual Model

Entity	Role
Person	Main entity (e.g. historical person)
Asset	Reusable referenced entity (documents, images, objects, etc.)

Relationship:

• One Person → many Assets
• One Asset → many Persons (implicit)

Drupal handles this naturally via **entity references**.

---

Required Modules

Ensure the following modules are enabled:

• Core:
  • Field
  • Views
• Contrib:
  • Inline Entity Form (IEF)
  • Entity Browser

No custom module is required.

---

Step 1: Create the Entity Reference Field

On the **Person** entity:

1. Go to:

   Structure → Content types → Person → Manage fields
   

2. Add a new field:

  * Field type: Entity reference
  * Label: Assets
  * Machine name: field_assets

3. Reference settings:

  * Target type: Asset
  * Allowed bundles: select relevant Asset bundles
  * Cardinality: Unlimited

Save the field.

---

Step 2: Configure the Form Widget (Critical Step)

1. Go to:

   Manage form display
   

2. For field_assets, select widget:

  * Inline Entity Form – Complex

3. Open the widget settings (gear icon):

  * ✅ Allow users to add existing entities
  * ❌ Allow users to add new entities
  * Entity Browser: select the Asset browser (configured in Step 3)

4. Save the form display.

Important: Do NOT select “Entity Browser” as the field widget itself. That widget does not provide a table‑based UI.

---

Step 3: Create the Entity Browser for Assets

1. Go to:

   Configuration → Content authoring → Entity Browser
   

2. Create a new browser:

  * Name: asset_browser
  * Display: Modal
  * Selection mode: Multi‑select

3. Add a widget:

  * Widget type: View

4. Create or select a View:

  * Base table: Asset
  * Display type: Entity Browser
  * Pagination: 10–25 items per page
  * Exposed filters:
    - Title
    - Type / taxonomy (as needed)
  * Fields:
    - Thumbnail (image style)
    - Title
    - Optional metadata

5. Save the Entity Browser.

---

Step 4: Resulting Editor UX

On the Person edit form:

• Assets are displayed in a table
• Editors can:

 - Add existing Assets
 - Remove Assets
 - Reorder Assets

• Clicking “Add existing Asset” opens a modal browser
• Assets are searched and selected visually

This provides a historian‑friendly workflow.

---

Step 4a: Table Representation on the Person Edit Form

The table‑based representation of linked Assets on the Person edit form is provided automatically by the **Inline Entity Form – Complex** widget.

This step documents how the table is configured and what editors see.

---

How the Table Is Generated

When the field field_assets is configured with:

• Widget: Inline Entity Form – Complex
• Cardinality: Unlimited

Drupal renders the referenced Assets as a **tabular list** instead of individual widgets.

No custom Views, no custom code, and no join tables are involved.

---

Default Table Columns

Out of the box, the table typically contains:

Column	Purpose
Label / Title	Identifies the linked Asset
Type / Bundle	Shows the Asset type (if applicable)
Operations	Remove / Edit actions
Weight	Drag‑and‑drop ordering

The exact columns depend on:

• Asset entity type
• Enabled fields
• Display settings

---

Editor Capabilities

Editors can:

• ✅ Add existing Assets (via Entity Browser)
• ✅ Remove Assets from the Person
• ✅ Reorder Assets using drag‑and‑drop
• ✅ See all linked Assets at once

This makes the relationship **explicit and transparent**, which is important for historical research workflows.

---

Why This Table Matters

Compared to alternative approaches:

Approach	Result
Autocomplete reference	Poor overview
Pills / tags	No metadata, no ordering
Custom join table	High complexity
IEF table	✅ Clear, structured, maintainable

The IEF table offers the best balance between:

• usability
• transparency
• maintainability
• upgrade safety

---

Configuration Notes

• No additional configuration is required beyond selecting

 Inline Entity Form – Complex.

• The table appears automatically on the Person edit form.
• Display styling is handled by the admin theme (Gin).

---

Extensibility

Later enhancements (optional):

• Add thumbnail columns
• Show additional Asset metadata
• Adjust column order or visibility

These enhancements can be achieved without changing the data model.

Step 5: UX Cleanup – Hide the Misleading “Add node” Button

Inline Entity Form displays an intermediate chooser containing an “Add node” button, which is misleading when creation is disabled.

This is hidden via Gin admin CSS.

CSS Location

sites/default/files/gin-custom.css

CSS Rule

/* Hide misleading "Add node" button in Inline Entity Form chooser */
input.ief-entity-submit[data-drupal-selector*="ief-reference-save"][value="Add node"] {
  display: none !important;
}

This solution:

• requires no JavaScript
• survives AJAX rendering
• is upgrade‑safe
• does not depend on dialog wrappers

---

Why No Join Table Was Used

An experimental approach using a “real” join table was evaluated and rejected because:

• it required a custom module
• it required schema lifecycle management
• UI construction required many hooks
• upgrades would require maintenance work

Drupal’s entity reference system already models the relationship correctly.

---

Performance Notes

• 1000+ Assets are handled without issue
• Only referenced Assets are rendered on the Person form
• Entity Browser uses pagination and indexed Views
• Thumbnails should always use image styles

---

Summary

This implementation achieves:

• ✅ Many‑to‑many relationship semantics
• ✅ Clean table‑based UI
• ✅ Visual asset selection
• ✅ No custom code
• ✅ No custom schema
• ✅ Upgrade‑safe architecture

This is the recommended approach for modern Drupal (11.x).

---

Reusability and Generalization of the Asset Linking Pattern

Purpose of This Section

The procedure described above is **not limited to Person → Asset**. It defines a **reusable architectural pattern** for linking Assets to any other entity type in Drupal.

This pattern enables true many‑to‑many semantics without custom code.

---

Core Idea

The solution separates concerns:

Concern	Mechanism
Relationship modeling	Entity reference field
Selection UX	Entity Browser
Management UX	Inline Entity Form (Complex)
Data storage	Drupal core entity system

Because of this separation, the same components can be reused.

---

Reusing the Entity Browser

The **Asset Entity Browser**:

• is generic
• operates on the Asset entity type
• does not depend on Person

Therefore, it can be reused **as‑is** for other entities.

Examples:

• Object → Asset
• Event → Asset
• Place → Asset
• Organisation → Asset

No changes to the browser are required.

---

Reusing the Pattern for Other Entities

To link Assets to another entity (e.g. Object):

1. Add an **Entity reference** field on the target entity:

  * Target type: Asset
  * Cardinality: Unlimited

2. Configure the form widget:

  * Widget: Inline Entity Form – Complex
  * Allow existing entities: ✅
  * Allow new entities: ❌
  * Entity Browser: reuse the existing Asset browser

3. Save the form display.

The result is identical:

• table‑based Asset management
• modal Asset selection
• no custom schema
• no custom code

---

Resulting Many‑to‑Many Relationship

When applied consistently:

• One Asset can be linked to many Persons
• One Asset can be linked to many Objects
• One Person can link many Assets
• One Object can link many Assets

Drupal handles this naturally via entity references.

No explicit join table is required.

---

Why This Works in Drupal

Drupal entities are first‑class, reusable objects. Entity references already implement relational semantics.

By reusing:

• the same Asset entity
• the same Entity Browser
• the same IEF table UI

the system behaves like a relational many‑to‑many model, while remaining configuration‑driven and upgrade‑safe.

---

Architectural Benefit

This approach:

• ✅ avoids schema duplication
• ✅ avoids custom join tables
• ✅ avoids module proliferation
• ✅ enforces UX consistency
• ✅ scales across entity types
• ✅ simplifies maintenance and handover

This is the recommended approach for modern Drupal (11.x).

---

Key Takeaway

Once the Asset linking pattern is implemented once, it becomes a **reusable building block**.

New relationships are created by configuration, not by programming. ``

Key Lesson

If a solution requires:

• custom join tables
• extensive hook usage
• complex UI overrides

…it is often a sign that Drupal already offers a better abstraction.