Help:Cargo template: Difference between revisions

Jump to navigation Jump to search

Help:Cargo template (view source)

Revision as of 02:42, 27 September 2025

4,038 bytes removed ,  27 September
→‎Example 2: Event Template with Dependencies
VisualWikitext
No edit summary
Line 72: Line 72:


After saving, visit <code>Special:CargoTables/Books</code> (or your table name) to verify the structure.
After saving, visit <code>Special:CargoTables/Books</code> (or your table name) to verify the structure.
 
===Field Options: dependent on and hidden===
When defining fields in a Cargo table with <code>#cargo_declare</code>, you can use special options to control how fields appear in <code>Special:Drilldown</code>, a tool that lets users filter and browse Cargo data. Two useful options are <code>dependent on</code> and <code>hidden</code>.
====dependent on====
The <code>dependent on</code> option links a field to another field in the same table. It ensures that this field only shows up in <code>Special:Drilldown</code> after the user selects a value for the other field. This is great for organizing data so users see relevant options in a logical order.*'''Example''': In a table about events, you might have a <code>Country</code> field and a <code>City</code> field. You can make <code>City</code> depend on <code>Country</code> so that <code>Special:Drilldown</code> only shows city options after a country is chosen.
<pre>
<noinclude>
{{#cargo_declare:
_table=Events
|Country=String (allowed values=USA,Canada,UK)
|City=String (dependent on=Country)
}}
</noinclude>
</pre>In this example, users must pick a country (like "USA") in <code>Special:Drilldown</code> before they can filter by city. This keeps the interface clean and relevant.
====hidden====
The <code>hidden</code> option tells Cargo not to show a field in <code>Special:Drilldown</code>. The field is still stored in the table and can be used in queries with <code>#cargo_query</code>, but it’s hidden from the drilldown interface. Use this for data that’s useful for queries but not for user filtering, like internal IDs or metadata.*'''Example''': In an events table, you might store <code>Attendance</code> for internal tracking but not want users to filter by it in <code>Special:Drilldown</code>.
<pre>
<noinclude>
{{#cargo_declare:
_table=Events
|EventName=String (mandatory)
|Attendance=Integer (hidden)
}}
</noinclude>
</pre>Here, <code>Attendance</code> is saved and queryable (e.g., to calculate average attendance), but it won’t appear as a filter option in <code>Special:Drilldown</code>.
===Tips===*Use <code>dependent on</code> to guide users through related filters, like choosing a state after a country.
*Use <code>hidden</code> for fields that are technical or not useful for browsing, to simplify the <code>Special:Drilldown</code> interface.
*Test your fields in <code>Special:Drilldown</code> to ensure they behave as expected.
== Part 2: The Template Parameters ==
== Part 2: The Template Parameters ==


Line 268: Line 294:
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>.
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> ==
== 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/15769"

Navigation menu