Saintapedia

Help:Cargo template: Difference between revisions

Help page Discussion

Help:Cargo template (view source)

Revision as of 02:23, 27 September 2025

10,603 bytes added ,  27 September 2025
no edit summary
VisualWikitext
No edit summary
No edit summary
Line 5: Line 5:
# '''The storage part''' (using <code>#cargo_store</code>): Saves the data into the Cargo table for querying.
# '''The storage part''' (using <code>#cargo_store</code>): Saves the data into the Cargo table for querying.


These parts are wrapped in tags like <code>&lt;noinclude&gt;</code> and <code>&lt;includeonly&gt;</code> to control what appears where. Documentation is added separately to guide editors. This page explains each part in detail, with examples, and covers how to use the tags and where to place documentation.
These parts are wrapped in tags like <code>&lt;noinclude&gt;</code> and <code>&lt;includeonly&gt;</code> to control what appears where. Documentation is added separately to guide editors. This page explains each part in detail, with examples, covers how to use the tags, and discusses approaches like using two templates or placing documentation in a subpage.


== Part 1: The Declaration (#cargo_declare) ==
== Part 1: The Declaration (#cargo_declare) ==
Line 179: Line 179:
This ensures data is stored reliably for querying.
This ensures data is stored reliably for querying.


== Using <noinclude>, <includeonly>
== Using Two Templates for Cargo ==
 
Instead of combining all three parts (declaration, parameters, and storage) in a single template, you can split the responsibilities across two templates: one for declaring the Cargo table and another for handling parameters and storage. This approach is useful in complex wikis where multiple templates need to feed data into the same table.
 
=== Why Use Two Templates? ===
Using two templates separates the table definition from data entry, which can:
* Make maintenance easier by keeping the table structure in one place.
* Allow multiple templates to store data in the same table, enabling varied displays or inputs for the same data structure.
* Reduce the risk of errors from duplicate declarations, as only one template defines the table.
 
=== How It Works ===
* '''Declaration Template''': This template contains only the <code>#cargo_declare</code> part, wrapped in <code>&lt;noinclude&gt;</code>. It defines the table structure and is not used directly on pages. Name it descriptively, like <code>Template:BooksTable</code>.
* '''Storage/Display Template''': This template contains the parameters and <code>#cargo_store</code> parts, wrapped in <code>&lt;includeonly&gt;</code>. It uses <code>#cargo_attach</code> to link to the declared table, then stores and displays data. This is the template editors use on pages, like <code>Template:Book</code>.
* When using the storage template, editors call it as usual (e.g., <code>{{Book|Title=Example}}</code>), and it stores data in the table defined by the declaration template.
 
=== When to Use It ===
* When multiple templates need to store data in the same table (e.g., one template for books and another for book reviews, both using the <code>Books</code> table).
* On large wikis where table structures are reused across many templates.
* When you want to centralize table management to simplify updates (e.g., changing a field type in one place).
 
=== Placement ===
* The declaration template is a standalone page with only <code>#cargo_declare</code> in <code>&lt;noinclude&gt;</code>.
* The storage/display template includes <code>#cargo_attach</code> and <code>#cargo_store</code> in <code>&lt;includeonly&gt;</code>, alongside the display code.
 
=== Tips ===
* Name the declaration template clearly (e.g., <code>Template:TableNameTable</code>) to avoid confusion.
* Ensure the storage template’s parameters match the fields in the declaration template.
* Document both templates, linking the storage template to the declaration template for clarity.
* Test the setup by storing data and querying it with <code>#cargo_query</code>.
 
=== Example: Two-Template Setup for Books ===
Here, <code>Template:BooksTable</code> declares the table, and <code>Template:Book</code> handles storage and display.
 
==== Template:BooksTable ====
<pre>
<noinclude>
{{#cargo_declare:
_table=Books
|Title=String (mandatory, unique)
|Authors=List (,) of Page
|Year=Integer
|Genres=List (;) of String (allowed values=Fiction;Non-Fiction;Sci-Fi;Mystery)
}}
 
== Documentation ==
This template declares the <code>Books</code> table for use by other templates, like {{Book}}.
 
[[Category:Cargo table declarations]]
</noinclude>
</pre>
 
==== Template:Book ====
<pre>
<noinclude>
== Documentation ==
This template stores and displays book data in the <code>Books</code> table, defined by [[Template:BooksTable]].
 
'''Parameters:'''
* Title: Book title (required)
* Authors: Comma-separated author names
* Year: Publication year
* Genres: Semicolon-separated genres
 
'''Usage:'''
{{Book|Title=Example Book|Authors=Author1,Author2|Year=2023|Genres=Fiction;Sci-Fi}}
 
[[Category:Cargo templates]]
</noinclude>
<includeonly>
{{#cargo_attach:_table=Books}}
{{#cargo_store:_table=Books}}
{|
! Title
| '''{{{Title|Unknown}}}'''
|-
! Authors
| {{#arraymap:{{{Authors|}}}|,|x|[[x]]|, }}
|-
! Year
| {{{Year|}}}
|-
! Genres
| {{{Genres|}}}
|}
</includeonly>
</pre>
 
This setup allows other templates (e.g., <code>Template:BookReview</code>) to also use the <code>Books</code> table by including <code>#cargo_attach</code>.
 
== Using <noinclude>, <includeonly> ==
 
These tags control what happens when a template is transcluded (used with <code>{{TemplateName}}</code>):
 
* '''<noinclude>''': Content inside these tags appears ONLY on the template page, not on pages using the template. Use for:
** <code>#cargo_declare</code> (runs once).
** Documentation (see below).
** Categories for the template page, like <code>[[Category:Templates]]</code>.
** Example: <code>&lt;noinclude&gt;[[Category:Cargo templates]]&lt;/noinclude&gt;</code>.
* '''<includeonly>''': Content appears ONLY when the template is transcluded, not on the template page. Use for:
** <code>#cargo_store</code> (runs per use).
** <code>#cargo_attach</code> (in two-template setups).
** The display code (parameters part).
* '''No tags''': Content without tags appears both on the template page and when transcluded. Use sparingly, e.g., for shared instructions, but avoid for Cargo functions to prevent duplication.
* '''<onlyinclude>''': Rarely needed for Cargo templates. Use to specify exactly what gets transcluded if you have complex mixed content.
 
'''Best Practices''':
* Wrap the entire template with <code>&lt;noinclude&gt;</code> for declarations/documentation and <code>&lt;includeonly&gt;</code> for storage/display.
* Always preview transclusions to check for errors.
 
== Documentation: Inline vs. {{Doc}} Subpage ==
 
Documentation helps editors understand how to use the template. You can place it directly on the template page (inline) within <code>&lt;noinclude&gt;</code> tags or in a separate subpage, typically named <code>Template:TemplateName/doc</code>, using the <code>{{Doc}}</code> template. We recommend using a <code>{{Doc}}</code> subpage for most Cargo templates due to its advantages.
 
=== Inline Documentation ===
Placing documentation in <code>&lt;noinclude&gt;</code> on the template page is simple and keeps everything in one place.
 
==== Example: Inline Documentation ===
<pre>
<noinclude>
== Documentation for Template:Book ==
This template stores book info in Cargo for querying.
 
'''Parameters:'''
* Title: Book title (required, string)
* Authors: Comma-separated authors (pages)
* Year: Publication year (integer)
* Genres: Semicolon-separated genres
 
'''Example usage:'''
{{Book|Title=Example Book|Authors=Author1,Author2|Year=2023|Genres=Fiction;Sci-Fi}}
 
For queries, use {{#cargo_query:tables=Books|fields=Title,Authors}} etc.
[[Category:Cargo templates]]
</noinclude>
</pre>
 
=== {{Doc}} Subpage Documentation ===
Using a subpage like <code>Template:Book/doc</code> involves creating a separate page with the documentation and including it on the template page with <code>{{Doc}}</code>.
 
==== Example: Template:Book/doc ====
Create a page at <code>Template:Book/doc</code> with:
 
<pre>
== Documentation for Template:Book ==
This template stores book info in the <code>Books</code> table for querying.
 
'''Parameters:'''
* Title: Book title (required, string)
* Authors: Comma-separated authors (pages)
* Year: Publication year (integer)
* Genres: Semicolon-separated genres
 
'''Example usage:'''
{{Book|Title=Example Book|Authors=Author1,Author2|Year=2023|Genres=Fiction;Sci-Fi}}
 
For queries, use {{#cargo_query:tables=Books|fields=Title,Authors}} etc.
 
[[Category:Template documentation]]
</pre>
 
Then, on <code>Template:Book</code>, add:
 
<pre>
<noinclude>
{{Doc}}
[[Category:Cargo templates]]
</noinclude>
</pre>
 
=== Differences and Advantages ===
{| class="wikitable"
! Aspect
! Inline Documentation
! {{Doc}} Subpage
|-
| '''Location'''
| On the template page in <code>&lt;noinclude&gt;</code>.
| On a separate subpage, included with <code>{{Doc}}</code>.
|-
| '''Ease of Setup'''
| Simpler: just add to the template page. No extra pages needed.
| Requires creating a subpage, which adds a step.
|-
| '''Maintenance'''
| Harder to update for complex templates, as documentation mixes with code. Risk of accidental edits to template logic.
| Easier to edit separately without touching the template code. Ideal for complex templates or frequent updates.
|-
| '''Clarity'''
| Can clutter the template page, especially if documentation is long.
| Keeps the template page clean, showing only code and a link to docs.
|-
| '''Collaboration'''
| All edits (code and docs) are in one edit history, which can be confusing.
| Separate edit history for documentation, making collaboration clearer.
|-
| '''Reusability'''
| Harder to reuse across multiple templates.
| Can be transcluded into multiple templates or help pages.
|-
| '''Wiki Standards'''
| Common for simple templates but less professional for large wikis.
| Standard for large wikis (e.g., Wikipedia). Encourages consistency.
|-
| '''Protection'''
| If the template is protected, documentation edits are restricted.
| Subpage can have different protection levels, allowing doc edits by more users.
|}
 
=== Recommendation ===
Use a <code>{{Doc}}</code> subpage for Cargo templates, especially on larger wikis or for templates with complex logic or extensive documentation. This keeps the template page focused on code, makes documentation easier to maintain, and aligns with MediaWiki best practices. For very simple templates with minimal documentation, inline placement in <code>&lt;noinclude&gt;</code> may be sufficient, but subpages scale better for most use cases.
 
== Full Template Examples ==
 
Here are complete template examples combining all parts.
 
=== Example 1: Template:Book ===
<pre>
<noinclude>
This is the "Book" template.
 
{{#cargo_declare:_table=Books
|Authors=List (,) of Page
|Genres=List (,) of String
|YearOfPublication=Date
|NumberOfPages=Integer}}
 
{{Doc}}
[[Category:Cargo templates]]
</noinclude>
<includeonly>
{{#cargo_store:_table=Books}}
{|
! Author(s)
| {{#arraymap:{{{Authors|}}}|,|x|{{#formredlink:form=Author|target=x}} }}
|-
! Genre(s)
| {{{Genres|}}}
|-
! Year of publication
| {{{YearOfPublication|}}}
|-
! Number of pages
| {{{NumberOfPages|}}}
|}
</includeonly>
</pre>
 
=== Example 2: Template:Author ===
<pre>
<noinclude>
This is the "Author" template.
 
{{#cargo_declare:_table=Authors
|Country=String}}
 
{{Doc}}
[[Category:Cargo templates]]
</noinclude>
<includeonly>
{{#cargo_store:_table=Authors}}
{|
! Country of origin
| {{{Country|}}}
|-
! Books
| {{#cargo_query:tables=Books|where=Authors HOLDS '{{PAGENAME}}'}}
|}
</includeonly>
</pre>
 
== See Also ==
* [[mw:Extension:Cargo|Cargo Extension Documentation]]
* [[Special:CargoTables|View Cargo Tables]]
 
[[Category:Help]]
[[Category:Cargo templates]]
Retrieved from "https://saintapedia.org/wiki/Special:MobileDiff/15768"