Mngr: Created page with "= Explanation of Page Forms Usage in Asset v2 = This page documents how and why '''Page Forms''' is used in Asset v2. It is intended as long-term reference documentation and is written to be readable months or years later without needing external context. ---- == Purpose of This Document == Page Forms syntax can be confusing because: * form definitions are not intuitive * field behavior is influenced by multiple parameters * Page Forms looks like it “does magic..."

2026-02-20T13:14:33Z

Created page with "= Explanation of Page Forms Usage in Asset v2 = This page documents how and why '''Page Forms''' is used in Asset v2. It is intended as long-term reference documentation and is written to be readable months or years later without needing external context. ---- == Purpose of This Document == Page Forms syntax can be confusing because: * form definitions are not intuitive * field behavior is influenced by multiple parameters * Page Forms looks like it “does magic..."

New page

= Explanation of Page Forms Usage in Asset v2 =

This page documents how and why '''Page Forms''' is used in Asset v2.

It is intended as long-term reference documentation and is written
to be readable months or years later without needing external context.

----

== Purpose of This Document ==

Page Forms syntax can be confusing because:

* form definitions are not intuitive
* field behavior is influenced by multiple parameters
* Page Forms looks like it “does magic” when it actually does not

This document explains the Asset v2 form configuration
'''line by line and by intention'''.

----

== Big Picture ==

In Asset v2, Page Forms is used only to:

* guide users during Asset creation
* collect structured input
* connect form fields to template parameters
* allow file upload inside a controlled workflow

Page Forms does NOT:

* generate identifiers
* rename files
* enforce immutability
* validate archival rules
* store data by itself

Page Forms is a '''user interface layer'''.

----

== Location of the Form ==

The form is defined in:

<pre>
Form:Asset
</pre>

This page is edited in source mode like any other wiki page.

----

== Form Metadata Section ==

At the top of the form:

<pre>
{{{info
|no summary
|no preview
|no minor edit
|no watch
|no footer
}}}
</pre>

What this does:

* Removes edit summary
* Removes preview
* Prevents minor edits
* Avoids watchlist clutter
* Removes standard footer elements

Why this exists:

* Asset creation is a controlled operation
* Reduces accidental interaction
* Keeps the UI simple for non-technical users

----

== Template Binding ==

<pre>
{{{for template|Asset}}}
</pre>

What it does:

* Binds this form to Template:Asset
* Every field defined below corresponds to a template parameter

Important rule:
'''Field names MUST match template parameter names exactly.'''

----

== Form Layout Table ==

<pre>
{| class="formtable"
...
|}
</pre>

This is pure HTML layout.

Why a table is used:

* Aligns labels and fields cleanly
* Predictable rendering
* Easier for non-technical users to read

This has no semantic meaning for Page Forms itself.

----

== Chapter Field ==

<pre>
{{{field|Chapter
|input type=combobox
|values from namespace=Chapter
|existing values only
}}}
</pre>

What it does:

* Shows a dropdown with auto-completion
* Only allows pages from namespace Chapter
* Prevents free-text input

Why this exists:

* Chapter must reference an existing entity
* Prevents spelling variants
* Enables reliable Cargo queries later

----

== Place and Organisation Fields ==

Both fields are defined similarly:

<pre>
{{{field|Place
|input type=combobox
|values from namespace=Place
|existing values only
|placeholder=Use Organisation instead
}}}
</pre>

and

<pre>
{{{field|Organisation
|input type=combobox
|values from namespace=Organisation
|existing values only
|placeholder=Use Place instead
}}}
</pre>

What this does:

* Allows selection of exactly one context
* Guides the user visually
* Does NOT enforce exclusivity by itself

Important:
The mutual exclusion rule is enforced later by JavaScript and Lua.

----

== Identifier (Label) Field ==

<pre>
{{{field|Label|readonly}}}
</pre>

What it does:

* Displays the identifier
* Prevents manual editing

Why this exists:

* Identifier is system-generated
* Users must see it
* Users must not change it

Readonly fields can still be stored in Cargo.

----

== Sequence Field ==

<pre>
{{{field|Sequence|readonly}}}
</pre>

What it does:

* Displays the numeric sequence
* Prevents editing

Why it exists:

* Sequence is derived data
* Useful for debugging and transparency
* Not user-editable

----

== File Upload Field ==

<pre>
{{{field|File
|input type=page
|namespace=File
|uploadable=yes
}}}
</pre>

What it does:

* Allows file selection or upload
* Upload happens only when Save is clicked
* Creates a File page if necessary

Why this configuration is used:

* This is the only configuration proven stable in Asset v1
* Avoids Special:Upload
* Keeps upload bound to Asset creation

Important:
The file is NOT renamed here.

----

== Original Filename Field ==

<pre>
{{{field|OriginalFilename|readonly}}}
</pre>

What it does:

* Displays the original local filename
* Filled automatically by JavaScript later
* Cannot be edited manually

Why this exists:

* Provenance
* User reassurance
* Archival traceability

----

== AssetType Field ==

<pre>
{{{field|AssetType
|input type=combobox
|values from namespace=AssetType
|existing values only
}}}
</pre>

Purpose:

* Classifies the Asset
* Supports filtering and querying
* Prevents uncontrolled vocabularies

----

== Parent Asset Field ==

<pre>
{{{field|Parent
|input type=combobox
|values from namespace=Asset
|existing values only
|placeholder=Top level
}}}
</pre>

What it does:

* Allows linking to an existing Asset
* Enables derivation trees

Why it is optional:

* Not all Assets are derived
* Top-level Assets are common

----

== Description and Notes Fields ==

<pre>
{{{field|Description|input type=textarea}}}
{{{field|Notes|input type=textarea}}}
</pre>

What they do:

* Provide free-form text areas
* No validation
* Stored as Text in Cargo

Separation rationale:

* Description = narrative meaning
* Notes = technical or archival remarks

----

== Save Button ==

<pre>
{{{standard input|save}}}
</pre>

What it does:

* Commits the page
* Uploads the file
* Triggers Cargo storage
* Triggers later automation

Important:
There is no “draft save” in Page Forms.

----

== Important Reminder ==

Page Forms:

* does not generate identifiers
* does not enforce immutability
* does not rename files
* does not validate archival rules

It only collects and passes values.

----

== Mental Model to Keep ==

You can safely remember:

* Page Forms = structured input UI
* Template = data + presentation
* Cargo = storage
* Automation happens elsewhere

----

== Status ==

This document is stable reference documentation.

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

ICT:Documentation:Page Forms in Asset v2 - Revision history