Cargo/Storing data

The creation of data structures, and storage of data, is done in Cargo exclusively via templates. Any template that makes use of Cargo needs to contain calls to the parser functions #cargo_declare and #cargo_store; or, more rarely, calls to #cargo_attach and #cargo_store. #cargo_declare defines the fields for a table of data, #cargo_store stores data within that table, and #cargo_attach specifies that a template stores its data in a table that has been defined elsewhere.

Declaring a table

A template that stores data in a table needs to also either declare that table, or "attach" itself to a table that is declared elsewhere. Since there is usually one table per template and vice versa, most templates that make use of Cargo will declare their own table. Declaring is done via the parser function #cargo_declare.

This function is called with the following syntax:

{{#cargo_declare:
_table = table_name
|field_1 = TypeOfField1
|field_2 = TypeOfField2
...etc.
}}

Neither the table name nor field names can contain spaces or dashes; instead, you can use underscores, CamelCase, etc. Underscores cannot be used at the beginning or end of table and field names.

The field description must start with the type of the field, and in many cases it will simply be the type. The following types are predefined in Cargo:

Field Type	Description	Unindexed?
`Page`	Holds the name of a page in the wiki (default max size: 300 characters)
`String`	Holds standard, non-wikitext text (default max size: 300 characters)
`Text`	Holds standard, non-wikitext text; intended for longer values	✔
`Integer`	Holds an integer
`Float`	Holds a real, i.e., non-integer, number
`Date`	Holds a date without time
`Start date`, `End date`	Similar to `Date`, but are meant to hold the beginning and end of some duration. A table can hold either no `Start date` and no `End date` field, or exactly one of both.
`Datetime`	Holds a date and time
`Start datetime`, `End datetime`	Work like `Start date` or `End date`, but include a time.
`Boolean`	Holds a Boolean value, whose value should be 1 or 0, or 'yes' or 'no' (see this section for Cargo-specific information on querying Boolean values)
`Coordinates`	Holds geographical coordinates
`Wikitext string`	Holds a short text that is meant to be parsed by the MediaWiki parser (default max size: 300 characters)
`Wikitext`	Holds longer text that is meant to be parsed by the MediaWiki parser	✔
`Searchtext`	Holds text that can be searched on, using the MATCHES command (requires MySQL 5.6+ or MariaDB 5.6+)
`File`	Holds the name of an uploaded file or image in the wiki (similar to Page, but does not require specifying the "File:" namespace) (default max size: 300 characters)
`URL`	Holds a URL (default max size: 300 characters)

Fields with lists of values

A field can also hold a list of any such type. To define such a list, the type value needs to look like "List (delimiter) of type". For example, to have a field called "Authors" that holds a list of string values separated by commas, you would have the following parameter in the #cargo_declare call:

|Authors=List (,) of String

Important: List fields must have a different name than the table (e.g. don't create Items.Items as a List (,) of String.

Field parameters

The description string can also have additional parameters; these all are enclosed within parentheses after the type identifier, and separated by semicolons. The current allowed parameters are:

Parameter	Description
`size=`	For fields of type "Page", "String", "Wikitext string", "File", "URL" and "Email", sets the size of this field, i.e., the number of characters; the default is set by the global variable $wgCargoDefaultStringBytes, which in turn has a default value of 300 (although it can be modified in LocalSettings.php).
`hierarchy`	Specifies that the field holds a hierarchy of values, as defined in the "allowed values" parameter (see next item).
`allowed values=`	A set of allowed values that a field can have. (This is usually only done for fields of type "String" or "Page".) If "hierarchy" is not specified, this should simply be a set of comma-separated values. If "hierarchy" is specified, the values should be defined using the syntax of a bulleted list. In brief: every value should be on its own line, each line should start with at least one "", the first line should start with exactly one "", and the number of "*" should increase by no more than one at a time.

For example, to define a field called "Color" that has three allowed values, you could have the following declaration:

|Color=String (size=10;allowed values=Red,Blue,Yellow)

Meanwhile, to define a field called "Main ingredient" that is a hierarchy, you could have the following declaration:

|Main_ingredient = String (hierarchy;allowed values=*Fruits
**Mangoes
**Apples
*Vegetables
**Root vegetables
***Carrots
***Turnips
**Peppers)

Parameter	Description
`link text=`	For fields of type "URL", sets text that would be displayed as a link to that URL. By default, the entire URL is shown.
`mandatory`	Takes no value. If set, the field is declared as mandatory, i.e., blank values are not allowed.
`unique`	Takes no value. If set, all values for the field must be unique – a value that already exists for that field in the table will not be saved.
`regex=`	Sets a regular expression for this field, which all values must match. For example, if "regex=T\d+" is set, values for that field must consist of the letter "T" followed by one or more numerals.

Attaching to a table

In some cases, you may want more than one template to store their data to the same Cargo table. In that case, only one of the templates should declare the table, while the others should simply "attach" themselves to that table, using the parser function #cargo_attach.

This function is called with the following syntax:

{{#cargo_attach:
_table = table_name
}}

A template should have no more than one call to #cargo_attach (and no more than one call to #cargo_declare, for that matter). Any template that contains a call to #cargo_store should also call either #cargo_declare or #cargo_attach.

Storing data in a table

A template that declares a table or attaches itself to one should also store data in that table. This is done with the parser function #cargo_store. Unlike #cargo_declare and #cargo_attach, which apply to the template page itself and thus should go into the template's <noinclude> section, #cargo_store applies to each page that calls that template, and thus should go into the template's <includeonly> section.

This function is called with the following syntax:

{{#cargo_store:
_table = table_name
|field_1 = value 1
|field_2 = value 2
...etc.
}}

The field names must match those in the #cargo_declare call elsewhere in the template.

The values will usually be template parameters or expressions derived from template parameters. Sometimes a constant value may be used, for example say multiple templates store to the Items table, then you might put the following at Template:Shield infobox:

{{#cargo_store:
_table = Items
|name = {{#or:{{{name|}}}|{{PAGENAME}}}}
|itemType=Shield
|weight={{{weight|}}}
...etc.
}}

Storing a recurring event

Special handling exists for storing recurring events, which are events that happen regularly, like birthdays or weekly meetings. For these, the parser function #recurring_event exists. It takes in a set of parameters for a recurring event (representing the start date, frequency etc.), and simply prints out a string holding a list of the dates for that event. It is meant to be called within #cargo_store (for a field defined as holding a list of dates), and #cargo_store will then store the data appropriately. #recurring_event is called with the following syntax:

{{#recurring_event:
start=start date
|end=end date
|unit=day, week, month, or year
|period=some number, representing the number of "units" between event instances (default is 1)
|include=list of dates, to be included in the list
|exclude=list of dates to exclude
|delimiter=delimiter for dates (default is ';')
}}

Of these parameters, only "start=" and "unit=" are required.

By default, if no end date is set, or if the end date is too far in the future, #recurring_event stores 50 instances of the event. To change this, you can add a setting for $wgCargoRecurringEventMaxInstances in LocalSettings.php, under the inclusion of Cargo. For instance, to set the number to 100, you would add the following:

$wgCargoRecurringEventMaxInstances = 100;

If working with recurring events, declare the type of the field of the field to be List (;) of Date.

Creating or recreating a table

No data is actually generated or modified when a template page containing a #cargo_declare call is saved. Instead, the data must be created or recreated in a separate process There are two ways to do this:

Web-based tab

From the template page, select the tab action called either "Create data" or "Recreate data". This will bring up an interface that may contain a checkbox reading "Recreate data into a replacement table, keeping the old one for querying". (That checkbox will only appear if the Cargo table in question already exists.)

Once you hit "OK", one of the following will happen:

If the checkbox was selected, a "replacement table" will be created, while the current table remains unaffected. This replacement table can be viewed by anyone, but its data will not be used in queries. (In the database, the actual table will have a name like "cargo__tableName__NEXT".) If/when you think this replacement table is ready to be used, you can click on the "Switch in table" link at Special:CargoTables. This link will delete the current Cargo table and rename the replacement table so that it becomes the official table. Conversely, if you would rather not use the replacement table, you can click on the "Delete" link for it.
If the checkbox was not selected, the current table will be deleted immediately, and a new version will get created.
If the checkbox was not there, it means that this is a new table. In that case, the table will be created.

In all three cases, MediaWiki jobs are used to cycle through all the relevant pages and recreate the data - a separate job is created for each page. This can be a lengthy process for large tables, which is why using the "replacement table" approach is recommended for large tables - it avoids a "downtime" period when the table is mostly empty.

Depending on the MediaWiki configuration, a call to MediaWiki's runJobs.php script may be useful or even necessary for these jobs to actually start.

If any templates contain #cargo_attach, they too will get a "Create data" or "Recreate data" tab. If this tab is selected and activated, it will not drop and recreate the database table itself; instead, it will only recreate those rows in the table that came from pages that call that template.

Permissions

The ability to create/recreate data is available to users with the 'recreatecargodata' permission, which on wiki.gg default is given to administrators.

Storing page data

You can create an additional Cargo table that holds "page data": data specific to each page in the wiki, not related to infobox data. This data can then be queried either on its own or joined with one or more "regular" Cargo tables. The table is named "_pageData", and it holds one row for every page in the wiki. You must specify the set of fields you want the table to store; by default it will only hold the five standard Cargo fields (_pageName, _pageTitle, _pageNamespace, _pageID and _ID: see Database storage details). To include additional fields, add to the array $wgCargoPageDataColumns in LocalSettings.php, below the line that installs Cargo.

Below are the fields that can be added to the _pageData table:

Field	Description
`_creationDate`	The date/time the page was created
`_modificationDate`	The date/time the page was last modified
`_creator`	The username of the user who created the page
`_lastEditor`	The username of the user who last modified the page
`_fullText`	The (searchable) full text of the page
`_categories`	The categories of the page (a list, queryable using "HOLDS"). The prefix "Category:" is not included All names are stored with the first letter uppercased, regardless of any displaytitles used Spaces are displayed as spaces (as opposed to underscores) Categories will only update on page creation, edit, or blank edit (and not e.g. if you edit a template to add a category but have not yet blank edited the pages transcluding that template) Order is not necessarily preserved relative to the lexicographic order in which categories are added on the content page
`_numRevisions`	The number of edits this page has had
`_isRedirect`	Whether this page is a redirect
`_pageNameOrRedirect`	The target of the page if it's a redirect, otherwise the page name
`_pageIDOrRedirect`	The ID of the target of the page if it's a redirect, otherwise the page ID

Once you have specified which fields you want the table to hold, go to the Cargo /maintenance directory, and make the following call to create, or recreate, the _pageData table:

php setCargoPageData.php

To recreate with replacement, add a --replacement flag:

php setCargoPageData.php --replacement

The replacement table can then be switched in normally using the Special:CargoTables interface.

If you want to get rid of this table, call the following instead:

php setCargoPageData.php --delete

You do not need to call the "--delete" option if you are planning to recreate the table; simply calling setCargoPageData.php will delete the previous version.

Storing file data

Similarly to page data, you can also automatically store data for each uploaded file. This data gets put in a table called "_fileData", which holds one row for each file. This table again has its own settings array, to specify which columns should be stored, called $wgCargoFileDataColumns.

There are currently five columns that can be set:

Field	Description
`_mediaType`	The media type, or MIME type, of each file, like "image/png"
`_path`	The directory path of the file on the wiki's server
`_lastUploadDate`	The date/time at which the file was last uploaded
`_fullText`	The full text of the file; this is only stored for PDF files
`_numPages`	The number of pages in the file; this is only stored for PDF files

To store the full text of PDF files, you need to have the pdftotext utility installed on the server, and then add the following to LocalSettings.php:

$wgCargoPDFToText = '...path to file.../pdftotext';

pdftotext is available as part of several packages. if you have the PdfHandler extension installed (and working), you may have pdftotext installed already.

To store the number of pages, you need to have the pdfinfo utility installed on the server, and then add the following to LocalSettings.php:

$wgCargoPDFInfo = '...path to file.../pdfinfo';

Once you have specified which fields you want the table to hold, go to the Cargo /maintenance directory, and make the following call to create, or recreate, the _fileData table:

php setCargoFileData.php

Navigation menu

Namespaces

Views

Navigation

wiki.gg

Policies & help

Tools

Cargo/Storing data

Contents

Declaring a table

Fields with lists of values

Field parameters

Attaching to a table

Storing data in a table

Storing a recurring event

Creating or recreating a table

Web-based tab

Permissions

Storing page data

Storing file data