View source for ICT:Template Inclusion and Transclusion Guide

= Template Inclusion and Transclusion Guide =

== Purpose ==
This page explains how MediaWiki controls what parts of a template are:

* visible on the template page itself
* visible when the template is used inside other pages (transcluded)

Understanding this mechanism is essential when building:

* Cargo storage templates
* Page Forms templates
* system templates

Incorrect usage can cause:
* wrong Cargo rows
* unwanted text on pages
* confusing behaviour

----

== Core concept: Transclusion ==

=== What is transclusion? ===

When a page contains:

  {{DigitalAsset}}

MediaWiki does NOT copy text.

Instead it:

# loads Template:DigitalAsset
# inserts its content dynamically
# renders the result

This process is called '''transclusion'''.

So a template has two different contexts:

{| class="wikitable"
! Context !! Meaning
|-
| Template page itself || Template:DigitalAsset is opened directly
|-
| Transcluded page || The template is used inside another page
|}

MediaWiki allows us to control what appears in each context.

----

== The three inclusion modes ==

=== 1. &lt;noinclude&gt; ===

Visible only on the template page itself.  
Hidden when the template is transcluded.

Use for:
* documentation
* instructions
* comments for editors
* maintenance notes

Example:

<pre>
<noinclude>
This template stores DigitalAssets in Cargo.
Do not edit manually.
</noinclude>
</pre>

Visible on:
 Template:DigitalAsset

Not visible on:
 DA:0001

----

=== 2. &lt;includeonly&gt; ===

Visible only when transcluded.  
Hidden on the template page itself.

Use for:
* Cargo storage
* categories
* logic
* anything that should affect real data pages

Example:

<pre>
<includeonly>
{{#cargo_store: ... }}
</includeonly>
</pre>

Runs on:
 DA:0001

Does NOT run on:
 Template:DigitalAsset

----

=== 3. No tags ===

Content without tags appears everywhere.

Visible:
* on template page
* on all pages using the template

Usually not desired for system templates.

----

== Why this matters for Cargo (very important) ==

Cargo executes:

  {{#cargo_store:}}

whenever the template is rendered.

If you do NOT use &lt;includeonly&gt;:

Opening:
 Template:DigitalAsset

would also execute cargo_store.

Result:
* unwanted database rows
* template page stored as data
* corrupted tables

Therefore:

'''All #cargo_store calls MUST be inside &lt;includeonly&gt;.'''

----

== Standard professional structure for Cargo templates ==

Recommended pattern:

<pre>
<noinclude>
Documentation for administrators and editors.
Explain fields and usage here.
</noinclude>

<includeonly>
{{#cargo_store:
 _table=DigitalAssets
 |id={{{id|}}}
 |file_id={{{file_id|}}}
}}
</includeonly>
</pre>

Meaning:

* documentation only visible to editors
* storage only happens on real pages

Clean separation of concerns.

----

== Mental model ==

Think of it like visibility scopes:

{| class="wikitable"
! Tag !! Visible to
|-
| noinclude || template editors only
|-
| includeonly || pages using the template only
|-
| none || everyone
|}

----

== Practical rules for this project ==

=== Cargo / data templates ===
Use:
* includeonly for all functional logic
* noinclude for documentation

=== Documentation templates ===
Usually no special tags needed

=== When unsure ===
Ask:
"Should this appear on the template page or only on real pages?"

----

== Common mistakes ==

{| class="wikitable"
! Mistake !! Result
|-
| cargo_store outside includeonly || unwanted rows created
|-
| documentation without noinclude || text appears on every page
|-
| mixing display and storage logic || hard to debug behaviour
|}

----

== Final advice ==

Templates are half content, half code.

Treat them like small programs:

* keep logic minimal
* keep behaviour explicit
* separate documentation from execution

Clarity prevents subtle bugs.