Quelltext der Seite Modul:CargoUtil/doc

{{documentation subpage}}
{{module rating|protected}}
<!-- Categories go at the bottom of this page and interwikis go in Wikidata. -->

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

== Usage ==
{{code|lang=lua|code=
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, data)|store(dbtable, stash)]]. See [[#Usage|Usage]]-example above. Please refer to the [https://www.mediawiki.org/wiki/Extension:Cargo/Storing_data#Declaring_a_table Cargo documentation page] fore more information about declaration options.
{{ambox|type=content|text=Warning: The declaration must be done on the template page and cannot be placed inside a &lt;includeonly&gt;-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.}}
;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 {{code snippet|lang=lua|code={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 <code>retainBlanks</code> 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. ...'
-->
{{code|lang=lua|code=
{
	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) ===
{{ombox|type=content|text=Warning: If you want to do anything other with the result than passing it to the output stream, you have to encapsulate it with {{code snippet|lang=lua|code=mw.text.unstrip()}}, otherwise you only get a strip marker as result!}}
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 <code>retainBlanks</code> 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 [[#declare(dbtable, declaration|declared]] and created before you can actually store anything.

{{ambox|type=info|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.}}

;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 {{code snippet|lang=lua|code={fieldName : data of type string or integer } }}
;return
:string, return values of the store call

[[Category:Class engine]]<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
<!-- Categories go here if you wish an additional category to that set in {{module rating}} above automatically. -->
[[Category:Lua metamodules]]
}}</includeonly>