|
|
| Line 1: |
Line 1: |
| = Understanding MediaWiki Cargo Templates =
| | [[Help:Cargo|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: |
| | |
| 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: | |
|
| |
|
| # '''The declaration part''' (using <code>#cargo_declare</code>): Defines the structure of the data table. | | # '''The declaration part''' (using <code>#cargo_declare</code>): Defines the structure of the data table. |
| Line 181: |
Line 179: |
| This ensures data is stored reliably for querying. | | This ensures data is stored reliably for querying. |
|
| |
|
| == Using <noinclude>, <includeonly>, and Related Tags == | | == 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><noinclude>[[Category:Cargo templates]]</noinclude></code>.
| |
| * '''<includeonly>''': Content appears ONLY when the template is transcluded, not on the template page. Use for:
| |
| ** <code>#cargo_store</code> (runs per use).
| |
| ** 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><noinclude></code> for declarations/documentation and <code><includeonly></code> for storage/display.
| |
| * Always preview transclusions to check for errors.
| |
| | |
| == Where to Place Documentation ==
| |
| | |
| Documentation helps editors understand how to use the template. Place it in <code><noinclude></code> at the top of the template page for visibility. Include:
| |
| * A brief description of the template’s purpose.
| |
| * A list of parameters (with types, defaults, and examples).
| |
| * A usage example, like <code>{{TemplateName|param1=value}}</code>.
| |
| * Notes on querying the Cargo table.
| |
| * Relevant categories, like <code>[[Category:Cargo templates]]</code>.
| |
| | |
| === Example 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>
| |
| | |
| == 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}}
| |
| | |
| == Documentation ==
| |
| Stores book data in the <code>Books</code> table.
| |
| | |
| '''Parameters:'''
| |
| * Authors: Comma-separated author names
| |
| * Genres: Comma-separated genres
| |
| * YearOfPublication: Publication date
| |
| * NumberOfPages: Page count (integer)
| |
| | |
| '''Usage:'''
| |
| {{Book|Authors=Author1,Author2|Genres=Fiction,Sci-Fi|YearOfPublication=2023|NumberOfPages=300}}
| |
| | |
| [[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}}
| |
| | |
| == Documentation ==
| |
| Stores author data and links to their books.
| |
| | |
| '''Parameters:'''
| |
| * Country: Author's country of origin
| |
| | |
| '''Usage:'''
| |
| {{Author|Country=USA}}
| |
| | |
| Query books with {{#cargo_query:tables=Books|where=Authors HOLDS '{{PAGENAME}}'}}.
| |
| | |
| [[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]]
| |