View source for ICT:Documentation:Cargo in Template Asset

= Explanation of Cargo Usage in Template:Asset =

This page documents how and why Cargo is used in '''Template:Asset'''.

It exists as long-term reference documentation and is intended to be read
slowly and re-read over time.

----

== Purpose of This Document ==

Cargo configuration is often difficult to understand because:

* it mixes schema definition and data storage
* it uses parser functions that look similar but behave very differently
* errors are often silent

This document explains, line by line, the Cargo-related parts of Template:Asset,
without involving Page Forms, JavaScript, or Lua.

----

== Big Picture ==

Cargo is used in Template:Asset for exactly two purposes:

# '''Declare the data structure''' (schema)
# '''Store data when a page is saved'''

Cargo does NOT:
* control page layout
* control page editing
* control file uploads
* control automation

Cargo only stores and retrieves structured data.

----

== Cargo Declaration Section ==

In Template:Asset, the Cargo declaration appears inside a <code>&lt;noinclude&gt;</code> section:

<pre>
<noinclude>
{{#cargo_declare:
 |_table=Assets
 |Code=Page
 |Label=String
 |Chapter=Page
 |Place=Page
 |Organisation=Page
 |Sequence=Integer
 |File=String
 |OriginalFilename=String
 |Parent=Page
 |AssetType=Page
 |Description=Text
 |Notes=Text
}}
</noinclude>
</pre>

This section defines the structure of the Cargo table.

----

== Why cargo_declare Is Inside &lt;noinclude&gt; ==

<code>&lt;noinclude&gt;</code> means:

* The declaration is part of the template definition
* It is NOT included when the template is transcluded into a page

Why this matters:

* The Cargo table is declared once
* It is not redeclared every time an Asset page is viewed
* Prevents schema duplication and errors

Important rule:
'''cargo_declare MUST always be inside &lt;noinclude&gt;.'''

----

== The Cargo Table Name ==

<pre>
|_table=Assets
</pre>

What it does:
* Defines the name of the Cargo table
* All Asset records are stored in this table

Why it matters:
* Table name is global and permanent
* Changing it later breaks all queries

In Asset v2, the table name '''Assets''' is locked.

----

== Field Definitions ==

Each line defines one field (column) in the table.

Example:

<pre>
|Label=String
</pre>

Meaning:
* Field name: <code>Label</code>
* Field type: <code>String</code>

Cargo types define how data is stored and queried.

----

== Explanation of Field Types Used ==

=== Page ===

Example:
<pre>
|Chapter=Page
</pre>

What it means:
* Stores a wiki page reference
* Enables linking and page-based queries

Used for:
* Chapter
* Place
* Organisation
* Parent
* AssetType
* Code (page name)

----

=== String ===

Example:
<pre>
|OriginalFilename=String
</pre>

What it means:
* Stores plain text
* No page linkage
* No namespace assumptions

Used for:
* Original filenames
* File names
* Labels

Important:
File is stored as String on purpose to avoid Page-type constraints.

----

=== Integer ===

Example:
<pre>
|Sequence=Integer
</pre>

What it means:
* Stores numeric values
* Enables numeric comparison and MAX() queries

Used for:
* Sequence numbering

----

=== Text ===

Example:
<pre>
|Description=Text
</pre>

What it means:
* Stores long free-form text
* No length limit

Used for:
* Descriptions
* Notes

----

== Cargo Store Section ==

Below the declaration, Template:Asset contains:

<pre>
{{#cargo_store:
 |Code={{FULLPAGENAME}}
 |Label={{{Label|}}}
 |Chapter={{{Chapter|}}}
 |Place={{{Place|}}}
 |Organisation={{{Organisation|}}}
 |Sequence={{{Sequence|}}}
 |File={{{File|}}}
 |OriginalFilename={{{OriginalFilename|}}}
 |Parent={{{Parent|}}}
 |AssetType={{{AssetType|}}}
 |Description={{{Description|}}}
 |Notes={{{Notes|}}}
}}
</pre>

This section is executed every time an Asset page is saved.

----

== What cargo_store Does ==

<code>#cargo_store</code>:

* Takes values from template parameters
* Writes them into the Cargo table
* Updates existing rows automatically

Important:
* It does NOT create pages
* It does NOT validate input
* It does NOT control editing

----

== Why Code Uses FULLPAGENAME ==

<pre>
|Code={{FULLPAGENAME}}
</pre>

Meaning:
* Stores the page name of the Asset
* Example:
  <code>Asset:CH03-BER-0007</code>

Why this matters:
* The page name is the authoritative identifier
* Cargo rows can always be linked back to their page

This field must never change after creation.

----

== Why Template Parameters Use Triple Braces ==

Example:

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

Meaning:
* Reads the value passed to the template
* Uses empty default if not provided

Triple braces are standard MediaWiki template syntax and are required.

----

== Important Reminder ==

Cargo does NOT enforce immutability.

Rules such as:
* “Identifier must not change”
* “OriginalFilename is immutable”

are enforced by:
* Page Forms configuration
* JavaScript
* user discipline
* server-side extensions

Cargo only stores what it is given.

----

== Mental Model to Keep ==

You can safely remember:

* cargo_declare = table definition
* cargo_store = data write operation
* Template parameters = data source
* Cargo does not control behavior

----

== Status ==

This document is stable reference documentation.

It exists to support long-term understanding and memory retention.