Help:Understanding Cargo

The MapleStory 2 Wiki uses the MediaWiki extension Cargo to store and maintain data. For more tech-savvy people, Cargo is essentially a wrapper for MySQL with limited MySQL functions. The Cargo documentation is fairly solid in helping people get an understanding of the extension in a general sense, but the following page will be a tutorial with an actual example related to MapleStory 2.

This tutorial does require some basic knowledge that won't be covered such as:
 * Knowledge of data types (eg. Integers, Strings, etc.).
 * A basic understanding of Wiki syntax, templates and how they work (eg. Knowing how to use templates, template syntax like triple brackets, etc.)

The example specifically will be using Cargo to create a table we can query of:
 * Player Name
 * Player Level
 * Player Server

Starting With a Template
A benefit of Cargo is that it can be implemented inside already existing templates.

For example, let's say we have a PlayerInfoExample template that takes in parameters of Name, Level, and Server. The PlayerInfo template formats it and displays the info in a table. The template would potentially look something like this:

Calling the template would look like this:

And when you save the page, it will display this:

We can seamlessly add Cargo into this template to start storing the parameters passed in and start keeping a table of PlayerInfo every time this template is called.

Source Code
The page(s) related to this tutorial is/are:
 * Template:PlayerInfoExample

Overview
Cargo can be stored into 3 actions:
 * Creating Tables to store data
 * Storing the Data
 * Querying the Data

Creating Cargo Tables
In order for us to store the data, first we have to create somewhere to store the data. This is what the Cargo tables are for. Additionally, you must also define:


 * What you're storing in the table
 * What kind of thing you're storing in the table

Example
As stated, the goal of this example tutorial is to create a table to store player names, levels, and servers.

1) Determine the name of the table.
 * Since this is just a table of player information, we can just call the table PlayerInfo.

2) Determine what we want to store
 * As stated, we want to store: Player Name, Player Level, and Player Server.

3) Determine what type these things should be.
 * The type refers to common data types (eg. String, Integer, Float, etc.) as well as some unique data types such as Wikitext (Refer to Cargo documentation for comprehensive list). This tutorial won't cover how to choose which type and assumes you are knowledgeable enough to know. If not, don't hesitate to ask other editors more familiar!
 * For this example, the types we choose for the three fields we want to create are:
 * Name - Type String
 * Level - Type Integer
 * Server - Type String

4) (Optional) Determine restrictions.
 * For some types, we want to set restrictions on the values that can be put into the table.
 * For example, there are only 5 servers currently: North America West, North America East, Europe, Oceania, and South America. We can create a restriction so that the Cargo table only stores these 5 values and no other values.

Now we can move on to actually writing the code to define the Cargo table.

Example Source Code
Based on the information from above, the code to declare the Cargo table will look like this:

Source Code Breakdown
 * Wrap  statements in   tags.
 * is the tag we use to tell the Wiki we want to create a table.
 * defines the table's name.
 * defines a table column, and the type of the table column. In this case, we made:
 * Columns of Name, Level, and Server
 * With Types String, Integer, and String respectively.
 * The Server column has a restriction of only allowing the five server names and no other values.

Recreating and Viewing Cargo Tables
Once the code has been written and saved into the template, the Cargo table can now be created. This can only be done by Administrators.

Once a table is created though, it is publicly viewable from the Special Page: Special:CargoTables. From here, you can view the example PlayerInfo Cargo table we've created as well as view the contents of the table.
 * Notice that the table also creates a default column called "Page" which stores the page name from where data is stored.

Summary Notes
Summary Notes:
 * Cargo tables are defined in Templates
 * Cargo tables are defined using
 * In the template code,  should be wrapped inside   tags.
 * After saving the template code, Cargo tables are created by going to More > Recreate Data.
 * However, only Administrators actually have the permissions to run it.
 * Created tables can be viewed at Special:CargoTables

Implementing Data Storing With Templates
Storing into Cargo uses. Similar to Cargo declare, you specify the name of the table you want as well as the columns.

Source Code
The syntax to store into a Cargo table is as follows:

We can then specify what values we want to store. For example:

However, we don't always want to specifically hardcode the values we want to store. This is where templates come in to play.

So, instead of using specific values, instead we use the PlayerInfo template parameters in the Cargo Store like the following:

Calling Template to Store Data
Now that we've defined how we want to store the data in the template, we can call and use the template to actually store data now. I've called the template in my User Sandbox User:Elaeagnifolia/Cargo. The syntax used is shown below:

Notice that the template syntax has NOT changed at all from the beginning. It is still called the same way as the beginning of the tutorial. However, if you go to the PlayerInfo Cargo table, you'll notice that now it has a row which contains the information I put into the template (Elaeagnifolia / 60 / North America East) as well as the page name where I called the template from.

Now the data is stored and can be queried for anywhere on the Wiki now!

Querying the Data
With the data stored, now we can use Cargo to query for information automatically vs. manually writing information out. For example, I can automatically pull my own information without having to look it up, create a list of which players in the table belong to a server, or get all the players over a certain level.


 * Cargo querying uses
 * The quickest way to see how querying works is probably through example, so go through the following examples to see the basics of how queries work and what they can do.
 * There are many parameters which can be specified which cannot be covered in all the examples below. See the official Cargo documentation for a more comprehensive list of parameters. Though, some of the common ones to use are:

Examples
For example purposes, I've added a couple more rows into the Cargo table which can be viewed on my User Sandbox page as well User:Elaeagnifolia/Cargo.

Example 1
Example 1 Goal: Query for my own player level.

Example 2
Example 2 Goal: Query for all player names where their levels are greater than 50.

Example 3
Example 3 Goal: Query for all player information on the server North America East, and format it into a table.