Modul:CargoUtil/doc

This module provides serveral useful function that can be used in other module to store or retrive data operating a cargo store.

Usage

local _CARGO = require('Module:CargoUtil')
if dataStore == 'cargo' and mw.title.getCurrentTitle().namespace == 10 then
	-- create table declaration, then call
	_CARGO.declare('tablename', declaration)
end
if stash then
	_CARGO.store('tablename', stash)
end
local query = {
	tables = {'table1'}
	fields = {'_pageName', '_ID', 'field1'}
	where = {'field1="hello world"', '_ID > 1'}
	order = {'_ID ASC', '_pageName DESC'}
}
local attributes = {
	limit = 1
}
local result = _CARGO.query(query, attributes)

Functions

Provided functions are as follow:

declare(dbtable, declaration)

Calls #cargo_declare with the provided parameter. Note that this parser function must be called (and therefore placed) on the template page, that later fills the table via store(dbtable, stash). See Usage-example above. Please refer to the Cargo documentation page fore more information about declaration options. {{#vardefine:ambox_color|warning}}

   {{#vardefine:ambox_image|Ambox important.svg}}{{#vardefine:ambox_imageSize|40x40px}}{{#vardefine:ambox_image|[[File:{{#var:ambox_image|Mbox notice.png}}|{{#var:ambox_imageSize|40x40px}}|alt=|link=]]}}{{#vardefine:ambox_content|{| class="metadata plainlinks"

|-

| class="mbox-image" |

{{#var:ambox_image}}

| class="mbox-text" |Warning: The declaration must be done on the template page and cannot be placed inside a <includeonly>-tag because in template space it creates a link in the toolbox (where you can also find "move" and "protect" buttons) to create the table. You have to do this in order to store data. |}

}}

{{#var:ambox_content|}}

dbtable

string, mandatory

takes the name of the database table that should be declared

declaration

table or string, mandatory

holds the declaration. if provided a table, it must be formatted {fieldName : 'declaration' }

return

string, return values of the declaration call

query(query, attributes, retainBlanks)

Runs a query on the cargo store according to the parameters provided and returns the result as a lua-table. The first parameter (query) has the following mandatory fields:

tables

table or string, mandatory

the name(s) of the table(s) to query data from

fields

table or string, mandatory

the fields, you want to get data from. format is fieldname or fieldname=headline. In case of more than one table, please use tablename.fieldname or tablealias.fieldname

joins

table or string, mandatory if you have more than one table. you need one join statement for each table after the first

the list of join statements

Also, there are several optional fields:

where

table or string, optional

you can filter the results with where clauses

group

table or string, optional

the group statements

having

table or string, optional

filter your query, similar to WHERE, but applies to values computed for "groups"

order

table or string, optional

the fields, you wish to sort the result for. please use tablename.fieldname or tablealias.fieldname

Please keep in mind:

• attributes may contain any attribute you find in the documentation, but intro and outro will be NILed, default and more results text will be set to the empty string, and format will be overwritten
• per default, does only return fields that contain a value. that can result in an "unbalanced" result, where one row contains more elements than others. if you want to get all fields, set retainBlanks to true

query

table, mandatory

the arguments to construct the query. see above for details

attributes

table, optional

more attributes, you want to pass on to the query (like limit, for instance)

retainBlanks

boolean, optional

if set to true, result can contain entries with empty values. per default, these entries will be deleted

return

table, see the following printout as example

The result has the following format: <-- cut 1: 1 = 'Extension:Cargo' 2 = '7' 3 = '901' 4 = 'Cargo provides a lightweight way to store and query the data contained within the calls to templates, such as infoboxes in mysql tables.' 2: 1 = 'Extension:SyntaxHighlight GeSHi' 2 = '6' 3 = '911' 4 = 'The SyntaxHighlight GeSHi extension provides rich formatting of source code using the "syntaxhighlight"-tag. ...' -->

{
	1 = {
		id = '7'
		pageid = '901'
		description = 'Cargo provides a lightweight way to store and query the data contained within the calls to templates, such as infoboxes in mysql tables.'
		page = 'Extension:Cargo'
	}
	2 = {
		id = '6'
		pageid = '911'
		description = 'The SyntaxHighlight GeSHi extension provides rich formatting of source code using the "syntaxhighlight"-tag. ...'
		page = 'Extension:SyntaxHighlight GeSHi'
	}
}

As you can see, the data fields can be indexed either by number or by the provided headline in table fields. (The headline is either the fieldname or a special string you provided via fieldname=headline.

rawquery(query, attributes)

Calls the parser function #cargo_query according to the provided parameters and passes the result on directly. The format of the output is depending on attributes.format. The first parameter (query) has the following mandatory fields:

tables

table or string, mandatory

the name(s) of the table(s) to query data from

fields

table or string, mandatory

the fields, you want to get data from. format is fieldname or fieldname=headline. In case of more than one table, please use tablename.fieldname or tablealias.fieldname

joins

table or string, mandatory if you have more than one table. you need one join statement for each table after the first

the list of join statements

Also, there are several optional fields:

where

table or string, optional

you can filter the results with where clauses

group

table or string, optional

the group statements

having

table or string, optional

filter your query, similar to WHERE, but applies to values computed for "groups"

order

table or string, optional

the fields, you wish to sort the result for. please use tablename.fieldname or tablealias.fieldname

Please keep in mind:

• attributes may contain any attribute you find in the documentation, but intro and outro will be NILed, default and more results text will be set to the empty string, and format will be overwritten
• per default, does only return fields that contain a value. that can result in an "unbalanced" result, where one row contains more elements than others. if you want to get all fields, set retainBlanks to true

query

table, mandatory

the arguments to construct the query. see above for details

attributes

table, optional

more attributes, you want to pass on to the query (like limit, for instance)

return

string, the renderd output

store(dbtable, stash)

Calls #cargo_store with the provided parameters. Note that the table must be declared and created before you can actually store anything.

{{#vardefine:ambox_color|info}}

   {{#vardefine:ambox_image|Information icon4.svg}}{{#vardefine:ambox_imageSize|40x40px}}{{#vardefine:ambox_image|[[File:{{#var:ambox_image|Mbox notice.png}}|{{#var:ambox_imageSize|40x40px}}|alt=|link=]]}}{{#vardefine:ambox_content|{| class="metadata plainlinks"

|-

| class="mbox-image" |

{{#var:ambox_image}}

| class="mbox-text" |Note: For security reasons, the data stored will be html-encoded. If you manually retrieve data from it (without using any of the query function), you have to decode manually. |}

}}

{{#var:ambox_content|}}

dbtable

string, mandatory

takes the name of the database table to be filled

stash

table (!), mandatory

holds the data to store. it must be formatted {fieldName : data of type string or integer }

return

string, return values of the store call