Help:Cargo
Cargo is a MediaWiki extension that acts as a middleman to allow storing and querying of data into MediaWiki's SQL database. This is incredibly helpful in keeping consistency by allowing us to automate several of the Wiki like tables, lists, even calendars of events, as long as we have the data stored. For example, if we create a new Memory page, List of Memories will automatically update without us needing to edit the page.
Having knowledge of source code editing and templates is essential for many of the Cargo templates the Wiki has. Visual Editor will not be able to do things like editing or querying Cargo functions.
Having a familiarity of the following is useful as well but not necessary:
- Field typing - When to use String, Integer, Date, DateTime, etc. and what values can be stored in them
- SQL querying - Parts of Cargo querying do use SQL syntax, but simple queries usually won't need too much in-depth knowledge.
For more detailed documentation, refer to the Cargo documentation pages
This is one of several Wiki editing guides, and it is highly recommended to review the ones related to your editing interests.
Process overview[edit source]
The process of using Cargo breaks down to the following:
- Creating a template that has a
#cargo_declare
- This will require you to come up with a data schema, or in less technical terms, a list of things you would like stored.
- Using
#cargo_storeto store data (On this Wiki, this is usually done in the same template as Step 1) - If using
#cargo_storein a a template, using that template on pages - Querying and making use of the data
To go through each of these aspects, we will be using Template:Call as our tutorial example.
Tutorial example[edit source]
For this tutorial, we will be using Template:Wanderer, a straightforward Cargo table that stores information on Wanderer enemies. Here are a list of helpful pages for this tutorial:
- Template:Wanderer
- Special:CargoTables/Wanderer
- List of Wanderers
- Luminivore (or any Wanderer page)
Creating a Cargo table[edit source]
- See also: mw:Extension:Cargo/Storing data
To store data, we need to create a template that has a #cargo_declare parser function in it to create the Cargo table. For this example, the template we'll be using is Template:Wanderer. Edit the source and find the #cargo_declare parser function.
- Make sure your #cargo_declare is inside the
<noinclude></noinclude>tags! - The parser function starts with
{{#cargo_declare: - We then specify the table name we want to create.
_table=Wanderer
- Keep table names simple! Ideally they should just be 1-2 words, with each word capitalized with no spaces (e.g. Wanderer, OutfitSet)
- Table names should not be plural unless the item specifically is plural. (e.g. Wanderer, not Wanderers)
- From here, we specify all the fields we want to store. For this template, you can see we're specifying:
- name
- imageName
- description
- battleGuide
- wandererFeature1-5
- We also want to specify what type we want these fields to be. You can find a full list on this Cargo page here, but generally the following are the most common we use on the Wiki:
- String - Useful for just storing text. Things like names, category names, etc.
- Wikitext - Useful for storing text that you want to keep formatted, like if your description contains links. It's not perfect though, so make sure what you're storing is basic templates.
- Integer - For number fields that don't need decimals
- Float - For number fields that need decimals
- Date/Datetime - Stores a date or date time. The Wiki standard is - in numerical form - <Year>-<Month>-<Day> <Hour>:<Minute>:<Second>. (e.g. 2024-01-25 05:00:00)
- Boolean - Stores a field of 1 or 0 / yes or no.
- For the Wanderer template, all the fields are pretty straightforward as Strings, so we put together the following:
|name=String |imageName=String |description=String |battleGuide=String |wandererFeature1=String |wandererFeature2=String |wandererFeature3=String |wandererFeature4=String |wandererFeature5=String
- Close the parser function.
}}
If you save the page here, you will now see your template page has a new option in the upper-right corner next to History called Recreate data. Clicking this button will create your new data table. If creating a completely new table, at this point, no data will be stored yet.
Note that this action is locked to administrator accounts to prevent vandalism of Cargo tables. Please contact someone with administrator-level perms to finish this step if you cannot!
Storing Cargo data[edit source]
- See also: mw:Extension:Cargo/Storing data
Now that the table has been created, we will move on to the next step - using the #cargo_store parser function to actually put data into the table.
Back in Template:Wanderer, look for the #cargo_store parser function. The format is very similar to #cargo_declare.
- Make sure #cargo_store is inside the
<includeonly></includeonly>tags! - The parser function starts with
{{#cargo_store: - We then specify the table name we want to store to.
_table=Wanderer - Next we go through every field we created, but instead of specifying a field type, we want to actually specify what we want to store. As this is a template, we will be using template variables to store.
|name={{{name|{{PAGENAME}}}}}
|imageName={{#invoke:String|replace|{{PAGENAME}}|:|}} icon.png
|description={{{description|}}}
|battleGuide={{{battleGuide|}}}
|wandererFeature1={{{wandererFeature1|}}}
|wandererFeature2={{{wandererFeature2|}}}
|wandererFeature3={{{wandererFeature3|}}}
|wandererFeature4={{{wandererFeature4|}}}
|wandererFeature5={{{wandererFeature5|}}}
- Close the parser function.
}}
Once you make the rest of the template and save it, you can now go use your template on a page to store data. For example in Luminivore's source code, our template looks like this:
{{Wanderer
|description=Its origin can be traced back to light and darkness. Often lurking in the shadows of objects. Aggressive towards sources of light, it can change its form.
|battleGuide=Be on the lookout when it quickly lunges at you. Take appropriate action when its form changes.
|wandererFeature1=Melee
|wandererFeature2=Shapeshifter
|wandererFeature3=
|wandererFeature4=
|wandererFeature5=
}}
- Notice that we don't specify a name field, but it will automatically store PAGENAME as the default.
Once you save this page, all the data will be stored into the Cargo table, congrats! Repeat this for everything you want to store. This is why the Wiki operates on a per-page basis for most items, although it is possible store multiple Cargo stores on a single page (See Events/Archive/2024).
To confirm that your data has been stored, you can always check the page's Page Values, which can be found by appending ?action=pagevalues to the URL (e.g. https://lads.wiki/wiki/Luminivore?action=pagevalues. On this page, you can see all the fields and what data was stored.
Querying Data[edit source]
Now that you've successfully stored all your data, it's time to use it. For this example, we will do a few basic examples. Keep in mind though that Cargo is very powerful and can get quite complex, so these examples only scratch the surface. There are many ways to query and make use of the various display formats that Cargo offers, from simple lists to calendars.
Getting all wanderers in a list[edit source]
This is a pretty common query, as we often make lists of data we store in Cargo. For this example, we keep the requirements simple. We just want an unordered list (bullet list) of all wanderers and their description. The query looks like this:
{{#cargo_query:tables=Wanderer
|fields=name,description
|format=ul
|limit=999
|group by=name
}}
The breakdown of this is as follows:
- The parser function starts with
{{#cargo_query: - We then specify the table name we want to store to.
tables=Wanderer
- Notice the lack of an underscore and tables not being singular compared to cargo_declare/cargo_store!
- We specify all the fields we want (name and description)
|fields=name,description - We specify the output format we want
|format=ul - We set a high limit to make sure we get all Wanderers as we want
|limit=999
- The default limit is 50 if you do not specify this.
- This is actually not a standard input for a query, but due to Cargo sometimes storing duplicates, we group all the duplicates with the same name.
|group by=name
The output we get looks like this (For the purposes of display, we've put it inside a collapsible):
| Cargo Output |
|---|
|
Getting all wanderers with the Melee feature[edit source]
The next example introduces where, which can be used to filter your results based on the condition you specify. For this example, we want to get all wanderers that have the Melee feature. This does mean we have to check all five features, since it's possible Melee might be stored somewhere else.
The query is very similar to the last example, but there is a new where line.
{{#cargo_query:tables=Wanderer
|fields=name
|where=wandererFeature1="Melee" or wandererFeature2="Melee" or wandererFeature3="Melee" or wandererFeature4="Melee" or wandererFeature5="Melee"
|format=ul
|limit=999
|group by=name
}}
An alternative to this instead of using all of these OR commands, is using the IN command instead, to check if the word "Melee" is in one of the wandererFeature fields.
{{#cargo_query:tables=Wanderer
|fields=name
|where="Melee" IN (wandererFeature1,wandererFeature2,wandererFeature3,wandererFeature4,wandererFeature5)
|format=ul
|limit=999
|group by=name
}}
| Cargo Output |
|---|
|
Using templates to make your output pretty[edit source]
One display format that we use on the Wiki is |template=format. What this means is you can go crazy with your HTML, CSS, etc. to make each output result customized as you want it. For example, List of Wanderers uses the template format.
However, Cargo has a bug where if you use the standard #cargo_query parser function with a template format, it will sometimes not render the query correctly.
We introduce Module:CargoQuery to this bug. The format is very similar, but has differences. For this example, we will take the query from the last example and instead output it with Template:Textcolor to turn the output names a purple color. We will also introduce a new function CONCAT The query is as follows:
{{#invoke:CargoQuery|main
|q?tables=Wanderer
|q?fields=name=text,CONCAT('purple')=color
|q?where="Melee" IN (wandererFeature1,wandererFeature2,wandererFeature3,wandererFeature4,wandererFeature5)
|q?limit=999
|q?groupBy=name
|template=Textcolor
}}
| Cargo Output |
|---|
| Bryo GolemCharybdis RexDark MystElysian LacertusElysian LupusFerrum ObscurumFlamma IgnisGlimmerbladeHerte KnaveHerte Knave: OriginalLuminivoreMagma KnaveMist KnavePumpkin MagusSnoozerTezcatlipocaTezcatlipoca RemnantTezcatlipoca ShardVulcaneon |
- We call the main function in Module:CargoQuery with
{{#invoke:CargoQuery|main - Notice that most of the lines now have
q?added to them. This is specific to the Module. - We have changed the
fieldsline a bit to|q?fields=name=text,CONCAT('purple')=color
- Template:Textcolor takes two variables: text and color. Notice that we've set
name=textandCONCAT('purple')=color
- Template:Textcolor takes two variables: text and color. Notice that we've set
- The CONCAT function allows for adding string content to your output. We don't have any field that would specify purple, so we just CONCAT the 'purple' string in ourselves.
- This can also be used with fields. For example,
CONCAT('Name: ', name)=textwould prependName:before the wanderer names in the previous query.
- This can also be used with fields. For example,
- Notice that
groupByis not separate using the Module. - Notice that the template we specify does not include
q?
