Module:Cargo/doc

This subpage provides documentation for Module:Cargo.

This is a meta module.

This module is meant to be used only by other modules. It should not be invoked in wikitext.

This module depends on the following other modules:

• Module:Arguments

Functions

m_cargo.declare

This function is a simple wrapper around cargo_declare.

m_cargo.attach

This function is a simple wrapper around cargo_attach.

m_cargo.store

This function is a wrapper around cargo_store.

It will cast certain native lua to acceptable values for the store. In particular:

• booleans -> cast to 1 or 0
• tables -> cast to a list separated by a delimiter (default is comma)

It will also avoid calling the store function if no values are passed.

Parameters

Parameter	Type	Description	Required	Default
frame	table	Frame object		—
values	assoc. table	Table containing key-value pairs to store in the table. It works exactly like cargo_store, expecting the key to be the of the field and the value the value to be stored. The _table field must be supplied as well.		—
args	assoc table	Additional parameters for this function		—
args.sep	assoc table	Table mapping the desired delimiter/separator for fields as value to the fields in question as key.		—
args.store_empty	boolean	Allows the storing of empty rows		false
args.debug	assoc table	If set, log the values written by this function to console		false

m_cargo.table_query

Function parameters

Parameter	Type	Description	Required	Default
tpl_args	table	Parsed template arguments. Please note those will be used/parsed by the function itself, see the template arguments section below. These will also be processed for selecting eligible display columns and passed to display functions.		—
frame	table	Frame object		—
main_table	string	The name of the main cargo table		—
row_unique_fields	array table	List of fields that identify a result as "unique". By default the page id is used.		<main_table>._pageID
empty_cell	string	HTML to use for empty fields		— by default
table_css	string	CSS class to add to table		—
data	table	Data table governing the display of table columns. For details see below.		—

Data parameters

Unless specified, each data entry is an array.

Parameter	Type	Description	Required	Default
data.tables	assoc table	table containing any extra conditions for tables as the "join" key.		—
args	array table	List of arguments that can be specified to display this column. The column will be shown if ANY of the parameter matches. If left empty, the column will always be shown.		—
header	string or function	Table header to display.		—
fields	array table	List of fully-qualified field names for this function (table + field). Fields will be automatically queried; if the table in the field is not the main table, a join clause must be added to the tables parameter. If a field is empty upon return, the cell will be considered empty. Please note that this behavior can be overridden in various ways with the options parameter.		—
display	function	Display function. The function will receive the following parameters (in this order): tpl_args - tpl_args as passed to this function frame - frame as passed to this function tr - HTML tr object rows - result rows for this cell rowinfo - this object (info for the current column)		—
order	int	Number to order this display cell by. Higher numbers will be shown at the end of the table, lower numbers will be shown first.		—
sort_type	string	Sort-type to use by table-sorter plugin		number
options	table array	Extra options for the fields. The index used here refers to the order in which the fields were specified.		—

Field option parameters

Placed at data[1 ... n].options[1 ... m]

Parameter	Type	Description	Required	Default
optional	boolean	If set to true, the field will not count as required for the display.		false

Template parameters consumed/used

Parameter	Type	Description	Required	Default
q_<cargo_lua_parameter>	string	Cargo parameter passed into the query function. Please note this is not exclusive and my be altered by the function itself. It is advised that at least q_where is specified, but not required. q_limit will not work currently.		—
default	string	Default text to display if no results are found.		No results found.
before	string	Text to prepend before the table.		—
after	string	Text to append after the table.		—

m_cargo.parse_field_arguments

Parses, and casts template arguments and maps them to a cargo argument table (i.e. the ones used in m_cargo.declare_factory).

The currently supported field types are:

• FLOAT, NUMBER - cast to number
• BOOLEAN - cast to boolean
• LIST OF ... - cast to table

Arguments

All arguments here are expected to be passed in single table to the function.

Parameter	Type	Description	Required	Default
tpl_args	assoc table	arguments passed to template after preprecessing		—
frame	assoc table	frame		—
table_map	assoc table	Table mapping for the arguments. See the relevant section below for more information.		—
rtr	boolean	If set return cargo key-value pairs instead of storing them into the database.		false

Map arguments

All arguments supplied here are for the mapping object. Some arguments are shared with m_cargo.declare_factory.

Parameter	Type	Description	Required	Default
order	array table	Array table for the order in which the arguments in map.fields will be parsed by their id. If a field is not present, it will not be parsed.		—
table	string	name of the table the fields belong to		—
fields	assoc table	Table containing the fields using their id as key and containing another assoc table containing the various options. The id used in the order.		—
fields[<id>].field	string	Name of the field in cargo table		—
fields[<id>].type	string	Type of the field in cargo table		—
fields[<id>].func	function	Function to handle the arguments.The function should return the parsed value. The function will be passed the following arguments in order: tpl_args - template arguments object frame - frame object value - parsed value of the field		—
fields[<id>].default	—	Default value if the value is not set or returned as nil If default is a function, the function will be called with (tpl_args, frame) and expected to return a default value for the field.		—
fields[<id>].name	string	Name of the field in tpl_args if it differs from the id in map.fields. For example used to internationalize names for example while keeping the code in English.		—
fields[<id>].required	boolean	Whether a value for the field is required or whether it can be left empty; essentially if whether storing NULL values is acceptable Note: With a default value the field will never be empty		false
fields[<id>].default	boolean	Skip field if missing from order and don't raise an error		false

m_cargo.map_results_to_id

Maps the results passed to a table containing the specified field as key and a table of rows for the particular page as values.

Arguments

All arguments here are expected to be passed in single table to the function.

Parameter	Type	Description	Required	Default
results	assoc table	table of results returned from mw.ext.cargo.query or m_cargo.query to map to the specified id field		—
field	string	name of the id field to map results to the field has to be in the fields list of the original query or it will cause errors		—
keep_id_field	boolean	If set, the id field won't be deleted from the result set. Note: The reason this is the default behavior is because the field is used as key already and doesn't need to be duplicated.		false

m_cargo.array_query

Performs a long OR query from the given array and field validating that there is only exactly one match returned

Arguments

All arguments here are expected to be passed in single table to the function.

Parameter	Type	Description	Required	Default
tables	array table	List of tables (see also m_cargo.query)		—
fields	array table	List of fields (see also m_cargo.query)		—
id_array	array table	List of id values to query for.		—
id_field	string	The id field to query for		—
query	table	table containing cargo sql clauses [optional] (see m_cargo.query)		—
ignore_missing	boolean	skip the check for missing fields entirely		—
warning_on_missing	boolean	issue warning to log/console instead of error if missing values		—

Return values

Type	Description
table	results as given by mw.ext.cargo.query
string	any error messages if it was used as warning

m_cargo.replace_holds

Replaces a "HOLDS" cargo query (which is currently bugged/broken) with a LIKE or REGEXP equivalent.

Arguments

All arguments here are expected to be passed in single table to the function.

Parameter	Type	Description	Required	Default
string	string	String to replace		—
mode	like or regex	Either of the specified modes: like: Replaces the holds query with a LIKE equivalent. regex: Replaces the holds query with a REGEXP equivalent. HOLDS LIKE is currently not supported though.		regex
field	sting	Field lua pattern to use. A different pattern from the default can be used to match only specific fields for replacement for example.		[%w_\.]+
separator	string	Separator for field entries to use in the REGEXP mode (corresponding to list declaration)		,

m_cargo.parse_field

Parse a cargo field declaration and returns a table containing the results

Arguments

All arguments here are expected to be passed in single table to the function.

Parameter	Type	Description	Required	Default
field	string	the field declaration string to parse		—

Return format

A table will be returned containing the following fields:

Parameter	Type	Description
type	string	type string of the field
list	string	Separator of the list, if the field is a "list" type. Nil otherwise
parameters	table	Table containing any parameters as keys and their values as values. Parameters that do not have a value will be set to "true".