View source for ICT:THE pattern

= ICT: Pattern — Dashboard, Page Form, Template, Cargo Table =

This page documents the standard pattern for creating structured data modules in the Costa Sano Research Archive.  
It applies to all entities stored in Cargo tables (e.g., Chapters, Persons, Locations, Events, Assets).

The pattern consists of four coordinated components:

# Template — stores data and writes to Cargo
# Form — provides a clean, simple editing UI
# Dashboard — lists records and links to the form
# Cargo table — automatically created from the template declaration

This pattern is stable, reproducible, and successor‑friendly.

----

== 1. Template (Template:EntityName) ==

The template defines:
* the Cargo table structure (via <code>#cargo_declare</code>)
* how data is stored (via <code>#cargo_store</code>)
* the form association (via <code>#forminput:form=…</code>)
* the display of the page itself

=== Structure ===

<pre>
<noinclude>
Documentation text…

{{#cargo_declare:
 _table=TableName
 |field1=String
 |field2=Text
 |field3=Date
 |field4=Page
}}

{{#forminput:form=EntityName}}
</noinclude>

{{#cargo_store:
 field1={{{field1|}}}
 |field2={{{field2|}}}
 |field3={{{field3|}}}
 |field4={{{field4|}}}
}}

== {{{field1|}}} ==
</pre>

=== Notes ===
* The <code>#forminput:form=EntityName</code> line is required so Page Forms knows which form edits pages using this template.
* Only fields declared in <code>#cargo_declare</code> may be stored.
* The template name must match the form’s <code>{{{for template|…}}}</code>.

----

== 2. Form (Form:EntityName) ==

The form provides a clean, simple UI for creating and editing records.  
It must:
* include an <code>info</code> block to hide clutter
* include a <code>standard input|save</code> button
* wrap fields inside a <code>for template</code> block

=== Structure ===

<pre>
<noinclude>
Form for creating and editing EntityName pages.
</noinclude>

{{{info
|no summary
|no preview
|no minor edit
|no watch
|no footer
}}}

{{{for template|EntityName}}}

{| class="formtable"
! Field 1
| {{{field|field1|mandatory}}}
|-
! Field 2
| {{{field|field2|input type=textarea}}}
|-
! Field 3
| {{{field|field3|input type=datepicker}}}
|-
! Field 4
| {{{field|field4|input type=combobox|values from namespace=EntityName}}}
|}

{{{standard input|save}}}

{{{end template}}}
</pre>

=== Notes ===
* The <code>info</code> block must appear before the <code>for template</code> block.
* The <code>standard input|save</code> line is required; without it, Page Forms falls back to the MediaWiki editor footer.
* The form name must match the template name.

----

== 3. Dashboard (Dashboard:EntityName) ==

The dashboard lists all records and provides a clean entry point to the form.

=== Structure ===

<pre>
= EntityName Dashboard =

{| class="wikitable sortable"
! Field1 !! Field2 !! Field3
{{#cargo_query:
 tables=TableName
 |fields=_pageName,field1,field2,field3
 |where=_pageNamespace=EntityNamespace
 |order by=field1
 |format=template
 |template=EntityRow
 |named args=yes
 |cache=no
}}
|}

{{#forminput:
 form=EntityName
 |namespace=EntityName
 |button text=➕ New EntityName
 |returnto=Dashboard:EntityName
}}
</pre>

=== Notes ===
* The dashboard never links to <code>action=edit</code>.
* All editing must go through Page Forms.

----

== 4. Row Template (Template:EntityRow) ==

This template defines how each row in the dashboard table is rendered.

=== Structure ===

<pre>
<includeonly>
|-
| {{#formlink:form=EntityName
    |target={{{_pageName}}}
    |link text={{{field1}}}
    |returnto=Dashboard:EntityName
  }}
| {{{field2}}}
| {{{field3}}}
</includeonly>
</pre>

=== Notes ===
* The first column is the clickable link that opens the form editor.
* <code>#formlink</code> ensures the user always enters <code>action=formedit</code>.

----

== 5. Workflow Summary ==

=== Creating a new record ===
* User clicks "New EntityName"
* URL: <code>Special:FormEdit/EntityName/EntityName:XYZ</code>
* Clean Page Forms UI appears
* Data is stored via <code>#cargo_store</code>
* Cargo table updates automatically

=== Editing an existing record ===
* User clicks the code in the dashboard
* URL: <code>EntityName:XYZ?action=formedit</code>
* Clean Page Forms UI appears
* Data updates in Cargo

=== No user ever sees the MediaWiki editor. ===

----

== 6. Rules for Reuse ==

To create a new module (e.g., Persons, Locations, Events):

# Copy the Template pattern → adjust fields
# Copy the Form pattern → adjust fields
# Copy the Dashboard pattern → adjust table and row template
# Create a Row template using <code>#formlink</code>
# Verify:
## Template name = Form name
## Cargo table name is unique
## Dashboard uses the correct namespace
## Form includes <code>standard input|save</code>

This pattern is stable, reproducible, and successor‑friendly.