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:

Form:Asset

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

Form Metadata Section

At the top of the form:

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

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

{{{for template|Asset}}}

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

{| class="formtable"
...
|}

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

{{{field|Chapter
 |input type=combobox
 |values from namespace=Chapter
 |existing values only
}}}

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:

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

and

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

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

{{{field|Label|readonly}}}

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

{{{field|Sequence|readonly}}}

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

{{{field|File
 |input type=page
 |namespace=File
 |uploadable=yes
}}}

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

{{{field|OriginalFilename|readonly}}}

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

{{{field|AssetType
 |input type=combobox
 |values from namespace=AssetType
 |existing values only
}}}

Purpose:

Classifies the Asset
Supports filtering and querying
Prevents uncontrolled vocabularies

Parent Asset Field

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

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

{{{field|Description|input type=textarea}}}
{{{field|Notes|input type=textarea}}}

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

{{{standard input|save}}}

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.