Module:Cargo/doc

Documentation &#91;[ purge]&#93;

This assembles a  call for the given Cargo table, provided its definition is in the   at the top of the module. This is used in a  section of a template to permit creating the table. The template in question is almost always going to be the same one making  calls in a   section to insert values into the table.

Usage is simple:

has to be used directly due to technical issues of framing and when Lua processing happens in the page save, so there is no store function in the module.

The  function of this module is an alternative to   with. It should not be used as an alternative to  for any other.

The latter is subject to an intermittent bug that causes output to appear as unrendered HTML requiring a purge to correct. The  function avoids the bug by processing the template transclusion in Lua after running the query through Cargo, rather than having Cargo perform both steps.

Usage is similar to a  call:

See Extension:Cargo/Querying data for more information, as the parameters here have the same usage as in  with the following exceptions:
 * cannot be used as an alternative to
 * is used instead of
 * is used instead of
 * is used instead of
 * This function always behaves as if  is
 * Very important: this module provides important special parameterization features  and  . Using these features allow a number of workarounds for certain Cargo bugs and limitations to be used automatically. In addition, it also handles certain escaping automatically. It is strongly recommended that the parameterization features be used on every query to prevent a number of avoidable errors and complications.

and parameterization
The parameterization features are similar to Parameterized queries used in many programming languages to avoid the security risks of SQL injection. They have different purposes here, but the way they are used in this module is similar in some ways.

This involves using "placeholders" in the  and   clauses where numeric or quoted values would usually go, and then supplying values for those placeholders in special arguments in the #invoke call. In the clauses, the placeholders are identified by a name in between two question marks, such as  or.


 * The name should begin with  for placeholders used where numeric values should go.
 * The name should begin with  for placeholders used where quoted values should go.

As an example, suppose you wanted to get all warriors over 3 star with the "Special" tag. Without using parameterization. Using a basic  call, it'd look something like this:

Using the  function of this module, the recommended way to write this would instead be something like this:

It's true that this simple case doesn't gain anything from it, but it would come in useful if:
 * Any of the values happened to contain text that matched the field names of one of the tables, as this triggers a known Cargo bug. This module automatically detects that as long as the  table at the top of this module is up to date and applies a workaround.
 * If any quoted value has quotes that are part of the value. This automatically escapes those quotes so they are handled correctly. Otherwise, if you were building a template to use arbitrary values, you'd have to use a  to escape them yourself.
 * This often comes in most useful in templates where the values aren't known in advance.

There is a more advanced parameterization feature used to work around limitations with using  or   on list fields in Cargo tables. As a general rule, you can only get away with using  or   once in a query, though it may work if you don't have to use them on different fields.

For example, say you were looking for all Warriors with tags "Special" and "Unique". The way to write this would seem to be:

But this will probably fail, as Cargo will probably not be able to construct a valid SQL query out of this.

This module has a workaround, and this workaround is recommended instead of using  or   at all. Instead, you'd write it something like this:

The module will construct a comparison for each that doesn't actually use  or , though usually give the same result, and can be used multiple times in a single query.

In more detail, the  or   workarounds are used like this:
 * Start the name with  to simulate   and   to simulate
 * Follow with the table name the field to check belongs to and follow that with a
 * Add the field name and then another  (this with the table name allows the module to look up the correct delimiter from its   table), which it needs to know.
 * After the last dot, it isn't actually necessary to add anything. Anything more just makes it a unique name, which is useful if you need to do multiple  checks on the same field. For example   would let you check for ships that have two specific abilities by passing those abilities through the arguments   and.
 * Using  or   here is recommended for readability.