Cargo: Quick start guide

From Gamepedia Help Wiki
Jump to: navigation, search
NOTE:
Prof hydra.svg Adapted from the Cargo extension documentation.


Let's say that you want to create a wiki that shows all the books you have at home. You want two kinds of pages on your wiki: one for books, and one for authors. Each book page should hold a title, an author name (or names), a genre (or genres), a year of publication, and a number of pages. Each author page should hold the author name, their country of origin, and a list of all the books they have written that you own.

Before getting started[edit | edit source]

If you want to use Cargo for the first time on your wiki, you have to have the Extension:Cargo enabled on your wiki. You can check by looking for it on Special:Version on your wiki. If it's not listed, follow the instruction on Requesting extensions. While you have Cargo added, make sure to also have enabled Page Forms extension - you'll need it too.

Creating the templates[edit | edit source]

The main thing you need to do is create two templates, one for books and one for authors. If you have the Page Forms extension installed, you can use either of its helper pages Special:CreateTemplate or Special:CreateClass to create these templates.

However, you can also manually create these templates. Here is what the two templates might look like:

Template:Book[edit | edit source]

<noinclude>
This is the "Book" template.

{{#cargo_declare:_table=Books
| Authors=List (,) of Page
| Genres=List (,) of String
| Year_of_publication=Date
| Number_of_pages=Integer
}}
</noinclude>
<includeonly>
{{#cargo_store:_table=Books
| Authors={{{Authors|}}}
| Genres={{{Genres|}}}
| Year_of_publication={{{Year of publication|}}}
| Number_of_pages={{{Number of pages|}}}
}}
{|
! Author(s)
| {{#arraymap:{{{Authors|}}}|,|x|{{#formredlink:form=Author|target=x}} }}
|-
! Genre(s)
| {{{Genres|}}}
|-
! Year of publication
| {{{Year of publication|}}}
|-
! Number of pages
| {{{Number of pages|}}}
|}
</includeonly>

Template:Author[edit | edit source]

<noinclude>
This is the "Author" template.

{{#cargo_declare:_table=Authors
| Country=String
}}
</noinclude>
<includeonly>
{{#cargo_store:_table=Authors
| Country={{{Country|}}}
}}
{|
! Country of origin
| {{{Country|}}}
|-
! Books
| {{#cargo_query:tables=Books
| where=Authors HOLDS "{{PAGENAME}}"}}
|}
</includeonly>

Summary[edit | edit source]

That is all you need to do to have infobox-style templates that both define a data structure and store their data in an easily-queried way.

You can see in this template examples of calls to the three main parser functions of Cargo: #cargo_declare, #cargo_store and #cargo_query; and hopefully how the three interact together. Note especially the placement of #cargo_declare and #cargo_store: the former in the <noinclude> tag, the latter in the <includeonly> tag.

A few other notes on these templates:

  • For both templates, the name of the entity, i.e the name of the book or author, is not stored in the template. That is because the name of the page itself will hold the name of that book or author -- and will also be stored in those two tables, in a field named "_pageName".
  • The "Author" template contains, at the end, what is known as an aggregating query, that queries the "Books" table (defined by the other template) and gets the names of all the pages that have the current page among its values for the "Authors" field. (It will then, by default, display that information in a comma-separated list.) This is a very common type of query; it means that you don't need to store the same data in two different pages, because one page can simply query the data.
  • There is one line of this sample code that requires another extension to work: the line in Template:Book which includes calls to both #arraymap and #formredlink, both of which are defined by the Page Forms extension. This line does a rather complex operation: it separates the value of "{{{Authors|}}}" into one or more sub-values (splitting by comma), then, for each value, either links directly to that page, if a page with that name already exists; or links to the form for creating that page, using the form definition at "Form:Author". Thus, this template presupposes not only that the Page Forms extension is installed, but that an "Author" form has been created. If you don't have Page Forms installed, you could replace that line with something a lot simpler, like:
| {{{Authors|}}}
However, Page Forms is strongly recommended for any wiki that uses Cargo.

Creating the Cargo tables[edit | edit source]

Once the templates are created, there's only one more simple step, which is to create the Cargo database tables for each template. This is not done automatically when the template is saved. Instead, there are two options:

  • For each template, go that template's page, select the "Create data table" tab option (or append ?action=recreatedata to the URL), then click the "OK" button.
  • From the command line, go to Cargo's /maintenance directory and run "php cargoRecreateData.php".

After doing either of these, a table will be created holding the data for each relevant template; and you will be able to see that table's contents at any time by clicking the "View table" link on the template's page.

Storing data in the Cargo tables[edit | edit source]

How to create data is explained in Storing data. The following example should only help you when you are doing it for the first time.

Create the following two pages with the following titles. This will automatically store the data in the Cargo tables, and in case of the page "Stephen King", query his book "The Shining". Feel free to create these examples with your favorite author.

Stephen King[edit | edit source]

{{Author
| Country=United States
}}

The Shining[edit | edit source]

{{Book
| Authors=Stephen King
| Genres=Horror
| Year of publication=1977
| Number of pages=447
}}

Viewing the Cargo tables[edit | edit source]

How to browse the Cargo data is fully explained in Browsing data. For now, the easiest way to look at your Cargo tables and data is Special:CargoTables.

What is next?[edit | edit source]

Look at the "Cargo manual" at the top of this wiki page for specific Cargo topics.