View source for ICT:Drupal CHANGE Code Caption

= Costasano Heritage Project — Asset Caption & Code Refactoring =

== Purpose of this Document ==

This document describes a proposed refactoring of the Asset ingestion workflow in the Costasano Heritage Project.

The goals of the refactoring are:

* eliminate duplicate typing during Asset creation
* ensure every Asset receives a meaningful short description
* simplify the workflow for contributors (70+ amateur historians)
* clarify the conceptual distinction between identifier and description
* remain fully compatible with the architectural blueprint

This change affects:

* Media entities
* the Asset entity
* the Asset creation workflow
* the custom Drupal automation module

The change does '''not''' affect:

* identifier generation logic
* the global counter
* file storage
* the authority entities (Chapter, Place, Organisation)

---

== Conceptual Model ==

The archive distinguishes three levels of textual description.
The archive distinguishes three levels of textual description.

The archive distinguishes three levels of textual description.

{| class="wikitable"
! Field        !! Meaning                               !! Typical Length !! Source
|-
| Code         || System‑generated archival identifier   || fixed          || system
|-
| Caption      || Short human‑readable label of the asset|| short          || user
|-
| Description  || Detailed contextual explanation        || long           || user
|}

Example record:

<pre>
Code: CH03-OOSTEN-00007
Caption: Construction of harbour bridge
Description:
Photograph taken during the installation of the steel beams of the
Oostende harbour railway bridge during the harbour expansion works of 1934.
</pre>

In Drupal terminology:

<pre>
Title field  → Caption
Description field → Long description
</pre>

---

== Current Implementation ==

The current workflow is:

<pre>
Upload media file
    ↓
Enter Media name
    ↓
Fill Asset Title (labelled Code)
    ↓
Save Asset
</pre>

Problems with this model:

* the Media Name and Asset Title represent the same concept
* users must type the caption twice
* the two values may diverge
* the interface is unnecessarily complex

---

== Target Model ==

The system will distinguish clearly between:

{| class="wikitable"
! Field       !! Purpose                          !! Editable
|-
| Code        || Archival identifier               || No
|-
| Caption     || Short human‑readable description  || Yes
|-
| Description || Detailed explanation              || Yes
|}|

The Caption will use the Drupal '''Title field'''.

The identifier will move to a dedicated field.

---

== Resulting Data Structure ==

Asset entity fields:

<pre>
Caption (Drupal Title field)
Code (field_as_code)
Counter
Chapter
Place / Organisation
Media
OriginalFileName
Description
Notes
</pre>

Media entity fields:

<pre>
Name (caption)
File
Metadata
</pre>

Relationship:

<pre>
Asset
  → Media
        → File
</pre>

Example Asset:

<pre>
Code: CH03-OOSTEN-00007
Caption: Construction of harbour bridge
Description: Photograph taken during installation of steel beams...
</pre>

---

== Proposed Ingestion Workflow ==

New workflow:

<pre>
Upload file
    ↓
Enter Media Name (caption)
    ↓
Create Asset
    ↓
System copies Media Name → Asset Caption
    ↓
System generates Code
</pre>

The caption is therefore entered '''once''' during media upload.

---

== Behaviour Rules ==

1. Media Name must be mandatory.
2. Caption is automatically populated when the Asset is created.
3. Caption is copied only during initial creation.
4. Later edits of Media must not overwrite the Caption.
5. Users may edit the Caption afterwards.
6. The Code field is system-generated and immutable.

---

== Migration Strategy ==

The current system already includes:

* Asset entity
* Media upload
* automatic identifier generation
* automatic filename capture

The following steps migrate the system to the new model.

---

=== Step 1 — Rename the Title Label ===

Location:

<pre>
Structure → Content types → Asset → Edit
</pre>

Change the Title label from:

<pre>
Code
</pre>

to:

<pre>
Caption
</pre>

The internal machine name remains:

<pre>
title
</pre>

Existing values remain unchanged.

---

=== Step 2 — Create the Code Field ===

Add a new field to the Asset content type.

Configuration:

<pre>
Label: Code
Machine name: field_as_code
Type: Text (plain)
Cardinality: 1
Required: No
</pre>

This field will contain the archival identifier.

---

=== Step 3 — Adjust the Custom Module ===

Modify the automation module.

Old behaviour:

<pre>
$entity->setTitle($identifier);
</pre>

New behaviour:

<pre>
$entity->set('field_as_code', $identifier);
</pre>

All other logic remains unchanged:

* counter generation
* filename extraction
* immutability rules

---

=== Step 4 — Make Media Name Mandatory ===

For each Media type:

<pre>
Structure → Media types → [Media type] → Manage fields
</pre>

Edit the field:

<pre>
Name
</pre>

Enable:

<pre>
Required
</pre>

Media types to update:

* Image
* Document
* Video
* Audio

---

=== Step 5 — Copy Media Name to Caption ===

Extend the custom module with logic:

<pre>
If Asset is new AND Caption empty
    read Media Name
    copy Media Name → Caption
</pre>

This ensures the Caption is filled automatically.

---

=== Step 6 — Adjust Asset Form Display ===

Reorganize the Asset form fields:

<pre>
Media
Chapter
Place / Organisation
Caption
Description
Notes
</pre>

Hide system fields:

<pre>
Counter
Code
OriginalFileName
</pre>

---

=== Step 7 — Adjust Dashboard Views ===

Update Asset dashboards to display:

<pre>
Code
Caption
Chapter
Context
</pre>

This keeps Assets recognizable in listings.

---

=== Step 8 — Validate Existing Records ===

After implementation verify:

* Code field populated correctly
* Caption preserved
* Identifier generation working
* Media linkage unaffected

No database migration is required because the Title field is only relabelled.

---

== Advantages ==

The refactoring provides:

* simplified ingestion workflow
* elimination of duplicate typing
* clearer conceptual model
* improved usability for non-technical contributors
* better alignment with archival cataloguing practice

---

== Risks and Side Effects ==

Possible side effects include:

* Views displaying the old Title label
* dashboards requiring field replacement
* module references still pointing to Title
* form display requiring adjustment

All should be verified after implementation.

---

== Compliance with Project Blueprint ==

The proposal respects the architectural principles:

* Asset remains the authoritative record
* Media remains the file container
* File remains the physical storage object

Automation assists data entry but does not change the authority model.

---

== Status ==

Proposed design change.

Implementation to be executed in controlled steps after validation.