Dynamic template layout elements — repeatable spacers and custom fields

[bcordis]

Problem

The current Layout Editor uses fixed, named fields in template.xml for each element (e.g., spacer1row, spacer2row, spacer3row). This means:

• Spacers are limited to 3 per context — if you need 4+ spacing points, you're stuck
• Custom fields are limited to 1 per context — can't have multiple custom code blocks
• Every new element requires XML field definitions — 5 fields per element × 4 contexts = 20 lines of XML per addition
• Template params JSON grows linearly with every possible element, even when most are unused (row=0)

Proposal

Allow dynamic creation of repeatable elements (spacers, custom fields) in the Layout Editor without pre-defined XML fields.

Key design questions

1. Storage format — How to store N dynamic elements in Joomla's params JSON?

   • Option A: Subform-style array (spacers: [{row: 2, col: 1, class: "my-3"}, ...])
   • Option B: Auto-numbered keys (spacer_1_row, spacer_2_row, dynamically generated)

2. Form rendering — How to show add/remove controls in the Layout Editor?

   • The Layout Editor already uses JS to manage elements — could extend with an "Add Spacer" button
   • Need to handle Joomla's AdminModel::save() → form->filter() stripping (the hidden field requirement)

3. Rendering engine — Cwmlisting::getListingBody() uses a fixed switch/case for element names

   • Dynamic elements would need a pattern-match approach (str_starts_with($name, spacer)) instead of exact match
   • Or a registry of element renderers

4. Migration — Existing templates with spacer1/spacer2/spacer3 need to continue working

Which elements should be repeatable?

Element	Repeatable?	Reason
Spacer	Yes	Layout gaps needed at multiple points
Custom code	Yes	Multiple custom HTML/code blocks
Scripture	No	Already handled by multi-scripture system
Teacher/Series/etc.	No	One per message
Media	No	Has its own display system

Scope

This would be a significant refactor of the template params architecture. Worth planning carefully before implementing.

Related

• PR feat: add spacer element for layout spacing #1178 — Added fixed spacer1/2/3 elements (current workaround)
• CLAUDE.md — Documents the template.xml hidden field requirement for syncToForm()

[bcordis]

This may help with other field names. We can create a single field name for the teacher, and based on where it was placed in the editor, it will know it was used on the teacher's detailed view on row 3. This could reduce the code needed to create content.

[bcordis]

Planning Notes

Unified Element Names (from @bcordis comment)

Instead of prefixed duplicates (tsteachername, tdteachername, dteachername), use a single canonical element name and let the Layout Editor context + position determine behavior:

// Current: 4 copies of every element
tsteachernamerow=1, tdteachernamerow=2, teachernamerow=1, dteachernamerow=3

// Proposed: one element, context-aware positioning
elements: [
  { name: "teachername", context: "teachers", row: 1, col: 1, element: "h3" },
  { name: "teachername", context: "teacherDetails", row: 2, col: 1, element: "h2" },
  { name: "spacer", context: "messages", row: 2, col: 1, class: "my-3" },
  { name: "spacer", context: "messages", row: 4, col: 1, class: "border-bottom" },
]

This collapses ~2,500 lines of template.xml into a compact array structure and naturally supports repeatable elements.

Proposed Storage Format

Store elements as a JSON array in a single params key per context:

{
  "layout_elements": {
    "messages": [
      { "name": "scripture1", "row": 1, "col": 1, "colspan": 2, "element": "p", "class": "", "link": 0 },
      { "name": "title", "row": 1, "col": 3, "colspan": 4, "element": "h3", "class": "", "link": 1 },
      { "name": "spacer", "row": 2, "col": 1, "colspan": 0, "element": "div", "class": "my-3" },
      { "name": "spacer", "row": 4, "col": 1, "colspan": 0, "element": "div", "class": "border-bottom" }
    ],
    "details": [],
    "teachers": []
  }
}

Joomla form-filter Problem

The biggest technical challenge: AdminModel::save() calls $form->filter() which strips any params not defined in the form XML. Options:

1. Single hidden field — store entire layout_elements JSON in one hidden field. Only 1 XML definition needed.
2. Override prepareData/save — intercept before filter and re-inject after.
3. Separate storage — store layout config in its own DB column instead of params JSON.

Option 1 is simplest and already proven (Layout Editor syncToForm() creates hidden inputs).

Migration Path

1. Keep reading old flat params (spacer1row, tsteachernamerow, etc.) as fallback
2. On first save through new editor, convert to layout_elements format
3. Old templates continue working until re-saved
4. Eventually remove legacy flat field support in a major version

Rendering Engine Changes

Current approach uses a fixed switch/case with ~50 cases. Proposed approach uses an element renderer registry where each element name maps to a render function. The renderer receives the item data and element config, and the framework wraps the output in the chosen HTML tag and CSS class. Repeatable elements (spacer, custom) just appear multiple times in the array.

Effort Estimate

Component	Hours
Storage format + migration	8
Layout Editor JS (add/remove/reorder)	12
Rendering engine refactor	8
Template.xml cleanup	4
Testing + backward compat	8
Total	40

Recommendation

This is a v11.0 candidate — it is a breaking change to template params storage. The current spacer1/2/3 workaround is sufficient for v10.x. Plan and prototype on a research branch.