Help:Cargo template

Cargo is a MediaWiki extension that lets you store structured data from wiki pages in database-like tables. This makes it easy to query and display data across your wiki. Templates are a key way to use Cargo, allowing editors to input data (like filling out a form) that gets saved and reused. A Cargo-enabled template has three main parts that work together to define, display, and store data:

1. The declaration part (using #cargo_declare): Defines the structure of the data table.
2. The parameters part (using parameters like {{{param}}}): Displays the data on pages where the template is used.
3. The storage part (using #cargo_store): Saves the data into the Cargo table for querying.

These parts are wrapped in tags like <noinclude> and <includeonly> 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)

The #cargo_declare part is where you define the structure of your Cargo table. Think of it as creating a blueprint for a spreadsheet, where you name the table and specify each "column" (field) with its data type (e.g., text, number, date). This sets up how data will be organized and stored.

Why Use It?

Without declaring the table and its fields, Cargo won't know how to store or organize the data. This step creates the table in the background (or updates it if you make changes). It’s done once per table, typically on the template page itself.

How It Works

You use the parser function

{{#cargo_declare:}}

with parameters:

• The first parameter is always _table=TableName (replace TableName with something descriptive, like Books).
• Then, list each field as |FieldName=Type (options). Common types include:
  • String: For text (e.g., titles, names).
  • Integer: For whole numbers (e.g., years, counts).
  • Date: For dates (e.g., publication date).
  • Page: For wiki page titles (e.g., author names as links).
  • List (,) of Type: For multiple values separated by commas or another delimiter (e.g., multiple authors).
• You can add options like:
  • mandatory: The field must be filled.
  • unique: No duplicate values allowed.
  • allowed values=Option1,Option2: Restricts input to a dropdown-like list.
  • dependent on=OtherField: Ties the field to another (e.g., Location depends on Country).
  • hidden: Hides the field from default displays but stores it.

Placement

Put #cargo_declare inside <noinclude> tags because it should only run on the template page itself, not every time the template is used. Without <noinclude>, you might get errors or duplicate declarations.

Tips

• Choose a unique, descriptive table name (e.g., Books, not Data). Avoid using a field name as the table name to prevent query issues.
• If your template adds data to an existing table (declared elsewhere), use

  {{#cargo_attach:_table=ExistingTable}}

  instead of #cargo_declare. This is useful when multiple templates feed one table.
• Changes to the declaration require recreating the table via Special:CargoTables (admin access may be needed).
• Keep fields minimal—only include what you’ll query later—to save space and improve performance.

Example 1: Simple Book Template Declaration

This declares a table for books with title, authors, year, and genres. The List type allows multiple authors or genres.

<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)
}}
</noinclude>

Example 2: Event Template with Dependencies

This includes a "Location" field that depends on "Country" and a hidden "Attendance" field for internal use.

<noinclude>
{{#cargo_declare:
_table=Events
|EventName=String (mandatory)
|StartDate=Date
|EndDate=Date
|Country=String (allowed values=USA,Canada,UK)
|Location=String (dependent on=Country)
|Attendance=Integer (hidden)
}}
</noinclude>

After saving, visit Special:CargoTables/Books (or your table name) to verify the structure.

Field Options: dependent on and hidden

When defining fields in a Cargo table with #cargo_declare, you can use special options to control how fields appear in Special:Drilldown, a tool that lets users filter and browse Cargo data. Two useful options are dependent on and hidden.

dependent on

The dependent on option links a field to another field in the same table. It ensures that this field only shows up in Special:Drilldown 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 Country field and a City field. You can make City depend on Country so that Special:Drilldown only shows city options after a country is chosen.

<noinclude>
{{#cargo_declare:
_table=Events
|Country=String (allowed values=USA,Canada,UK)
|City=String (dependent on=Country)
}}
</noinclude>

In this example, users must pick a country (like "USA") in Special:Drilldown before they can filter by city. This keeps the interface clean and relevant.

hidden

The hidden option tells Cargo not to show a field in Special:Drilldown. The field is still stored in the table and can be used in queries with #cargo_query, 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 Attendance for internal tracking but not want users to filter by it in Special:Drilldown.

<noinclude>
{{#cargo_declare:
_table=Events
|EventName=String (mandatory)
|Attendance=Integer (hidden)
}}
</noinclude>

Here, Attendance is saved and queryable (e.g., to calculate average attendance), but it won’t appear as a filter option in Special:Drilldown.

===Tips===*Use dependent on to guide users through related filters, like choosing a state after a country.

• Use hidden for fields that are technical or not useful for browsing, to simplify the Special:Drilldown interface.
• Test your fields in Special:Drilldown to ensure they behave as expected.

Part 2: The Template Parameters

The parameters part is where the template defines and displays the data entered by editors. Parameters are the values users provide when calling the template, like Template:TemplateName. They’re shown using triple braces, e.g., {{{param1}}}. This part creates the visible output, like an infobox or formatted text, based on those inputs.

Why Use It?

Parameters make the template user-friendly by displaying data in a readable way. Without this, the template would only store data invisibly, with no output on the page.

How It Works

• Parameters can be anonymous ({{{1}}} for the first parameter) or named (default value).
• In Cargo templates, parameter names often match the field names from #cargo_declare for easy storage.
• You can format the output using wikitext (e.g., bold, links, tables) or parser functions like #arraymap for lists (e.g., turning "Author1,Author2" into links) or #if for conditionals (e.g., show "Unknown" if a parameter is empty).
• For lists, use #arraymap to process multiple values, like linking each author to their page.

Placement

Put this part inside <includeonly> tags, alongside #cargo_store, so it only appears when the template is used on a page, not on the template page itself. Without <includeonly>, the output might clutter the template page.

Tips

• Use defaults like

  {{{param|}}}

  to avoid errors if a parameter is blank.
• Match parameter names to Cargo fields (replacing spaces with underscores if needed) for automatic storage.
• Use wiki tables, divs, or other formatting for clean layouts.
• Test with sample data to ensure the display looks good.

Example 1: Simple Book Template Parameters

This displays book info in a table, with parameters matching the declared fields.

<includeonly>
{|
! Title
| '''{{{Title|Unknown}}}'''
|-
! Authors
| {{#arraymap:{{{Authors|}}}|,|x|[[x]]|, }}
|-
! Year
| {{{Year|}}}
|-
! Genres
| {{{Genres|}}}
|}
</includeonly>

Example 2: Event Template with Conditional Display

This shows event details with a map link if a location is provided.

<includeonly>
== {{{EventName|Untitled Event}}} ==
* '''Start:''' {{#if:{{{StartDate|}}}|{{{StartDate}}}|TBD}}
* '''End:''' {{#if:{{{EndDate|}}}|{{{EndDate}}}|TBD}}
* '''Country:''' {{{Country|}}}
* '''Location:''' {{#if:{{{Location|}}}|{{{Location}}} ([[Special:Map|View Map]])|Not specified}}
* '''Attendance:''' {{{Attendance|0}}}
</includeonly>

This part makes the template dynamic and user-friendly.

Part 3: The Storage (#cargo_store)

The #cargo_store part saves the parameter values into the Cargo table, making them available for queries with #cargo_query.

Why Use It?

Without storage, the data isn’t saved in the table, so you can’t query it later (e.g., to create lists or charts).

How It Works

• Use , listing fields like |FieldName={{{param}}}.
• If parameter names match field names exactly, you can use just or even (if auto-fallback is enabled).
• For recurring events (e.g., weekly meetings), wrap in #recurring_event with options like start=, unit=days, and period=.

Placement

Place #cargo_store inside <includeonly> tags so it runs every time the template is used, storing data for each page.

Tips

• Storage happens automatically when a page is saved, updating the table with edits.
• For large wikis, explicitly list fields for speed and clarity.
• If using #cargo_attach, pair it with #cargo_store in the same way.
• Place it early in <includeonly> to ensure storage even if the display fails.

Example 1: Simple Book Template Storage

Assumes parameters match fields for auto-fallback.

<includeonly>
{{#cargo_store:_table=Books}}
</includeonly>

Example 2: Event Template with Recurring Storage

Explicitly lists fields for a recurring event.

<includeonly>
{{#cargo_store:_table=Events
|EventName={{{EventName}}}
|#recurring_event:start={{{StartDate}}}|end={{{EndDate}}}|unit=weeks|period=1
|Country={{{Country}}}
|Location={{{Location}}}
|Attendance={{{Attendance}}}
}}
</includeonly>

This ensures data is stored reliably for querying.

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 #cargo_declare part, wrapped in <noinclude>. It defines the table structure and is not used directly on pages. Name it descriptively, like Template:BooksTable.
• Storage/Display Template: This template contains the parameters and #cargo_store parts, wrapped in <includeonly>. It uses #cargo_attach to link to the declared table, then stores and displays data. This is the template editors use on pages, like Template:Book.
• When using the storage template, editors call it as usual (e.g., Template:Book), 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 Books 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 #cargo_declare in <noinclude>.
• The storage/display template includes #cargo_attach and #cargo_store in <includeonly>, alongside the display code.

Tips

• Name the declaration template clearly (e.g., Template:TableNameTable) 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 #cargo_query.

Example: Two-Template Setup for Books

Here, Template:BooksTable declares the table, and Template:Book handles storage and display.

Template:BooksTable

<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>

Template:Book

<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>

This setup allows other templates (e.g., Template:BookReview) to also use the Books table by including #cargo_attach.

Using <noinclude>, <includeonly>

These tags control what happens when a template is transcluded (used with Template:TemplateName):

• <noinclude>: Content inside these tags appears ONLY on the template page, not on pages using the template. Use for:
  • #cargo_declare (runs once).
  • Documentation (see below).
  • Categories for the template page, like [[Category:Templates]].
  • Example: <noinclude>[[Category:Cargo templates]]</noinclude>.
• <includeonly>: Content appears ONLY when the template is transcluded, not on the template page. Use for:
  • #cargo_store (runs per use).
  • #cargo_attach (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 <noinclude> for declarations/documentation and <includeonly> 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 <noinclude> tags or in a separate subpage, typically named Template:TemplateName/doc, using the {{Doc}} template. We recommend using a {{Doc}} subpage for most Cargo templates due to its advantages.

Inline Documentation

Placing documentation in <noinclude> on the template page is simple and keeps everything in one place.

Example: Inline Documentation

<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>

{{Doc}} Subpage Documentation

Using a subpage like Template:Book/doc involves creating a separate page with the documentation and including it on the template page with {{Doc}}.

Example: Template:Book/doc

Create a page at Template:Book/doc with:

== 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]]

Then, on Template:Book, add:

<noinclude>
{{Doc}}
[[Category:Cargo templates]]
</noinclude>

Differences and Advantages

Aspect	Inline Documentation	{{Doc}} Subpage
Location	On the template page in <noinclude>.	On a separate subpage, included with {{Doc}}.
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 {{Doc}} 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 <noinclude> 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

<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>

Example 2: Template:Author

<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>

See Also

• Cargo Extension Documentation
• View Cargo Tables