Modul:SmwUtil/doc

This module provides serveral useful function that can be used in other module to store or retrive data using semantic annotations.

Usage

local _SMW= require('Module:SmwUtil')
if dataStore == 'smw' and stash then
	_SMW.set(stash)
end
local query = {
	select = {'[[is public::yes]]', '[[is of type::datasheet]]', '[[has id::>>10]]'}
	fields = {'_CDAT=Create date', 'bears name=nickname', 'works as=occupation', 'has siblings'}
}
local attributes = {
	limit = 10,
	mainlabel ='-'
}
local result = _SMW.ask(query, attributes)

Functions

Provided functions are as follow:

ask(query, attributes, retainBlanks)

Runs an ask query on the semantic mediawiki triple store according to the parameters provided and returns the result as a lua table. The first parameter (query) has the following fields:

select

table or string, mandatory

the condition the query filters for. can be of string and arbitrarily complex or a table being either of format { propertyname = 'value' }, { '[[propertyname::value]]' } or a mix of both

fields

table or string, optional

the fields, you want to get data from. format of values is fieldname or fieldname=headline (you can skip the preceeding ?). DO NOT USE AN ARRAY! All keys will be discarded! Please uses string only if you have just one field to display. If you want to format the fields and add a headline, please do it before the =, e.g. fieldname#km2=area

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 ask 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, query result as a lua table. see the following printout as example

{
	1 = {
		1 = 'Extension:Cargo'
		has id = '7'
		references = { '901', '821' }
		description = 'Cargo provides a lightweight way to store and query the data contained within the calls to templates, such as infoboxes in mysql tables.'
		MainLabel = 'Extension:Cargo'
	}
	2 = {
		1 = 'Extension:SyntaxHighlight GeSHi'
		has id = '6'
		references = '911'
		description = 'The SyntaxHighlight GeSHi extension provides rich formatting of source code using the "syntaxhighlight"-tag. ...'
		MainLabel = '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. The mainlabel always has number 1 and whatever you passed on to attribute mainlabel (if nothing, default is MainLabel).

get(page, field)

A shortcut for show(page, field).

lua(query, attributes, retainBlanks)

A shortcut for ask(query, attributes, retainBlanks).

queryParserHelper(frame)

The is a query helper function invoked by the template used by the ask function. It formats the query result fields in a unique way, so that the query function can easily construct a table from your request.

frame

object, mandatory

the frame object, supplied by the template

return

string, formatted query result fields

rawask(query, attributes)

Calls the parser function #ask 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:

select

table or string, mandatory

the condition the query filters for. can be of string and arbitrarily complex or a table being either of format { propertyname : 'value' }, { '[[propertyname::value]]' } or a mix of both

fields

table or string, optional

the fields, you want to get data from. format is fieldname or fieldname=headline (you can skip the preceeding ?). Please uses string only if you have just one field to display. If you want to format the fields and add a headline, please do it before the =, e.g. fieldname#km2=area

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 ask query (like limit, for instance)

return

string, the renderd output

set(stash)

Stores provided stash in semantic triple stores.

stash

string or table, mandatory

data to store. if provided as string 'has property=value', one triple can be stores. if provided as table, you can either use { has property = 'value' }, { 'has propert=value' }, or a mix thereof. Even { has property = {'value1', 'value2', 'value3' } is possible.

return

string, hopefully empty, result of set parser function

show(page, field)

Returns contents of field stored on page

page

string, mandatory

name of page, to get the property contents from (please include namespace but explude brackets), e.g. 'Meta:Mail'

field

string, mandatory

name of property, to get the contents from. You can skip the '?'

return

string, contents of property 'field' on page

subobject(stash, uid)

Stores provided stash as a subject. Contrary to set(stash) the data is not stored directly on the page but in a separate entity called subobject. These objects can be queried for separately.

stash

string or table, mandatory

data to store. if provided as string 'has property=value', one triple can be stores. if provided as table, you can either use { has property = 'value' }, { 'has propert=value' }, or a mix thereof. Even { has property = {'value1', 'value2', 'value3' } is possible.

uid

string, optional

You can supply a uid to identify the object by. Just make sure, it is unique. :)

return

string, hopefully empty, result of set parser function

The Helper Template

In order for the ask query funtion to work, you need to have a helper template created that invokes the queryParserHelper function. If not present, please navigate to {{SmwUtilQueryParserHelper}} and provide the following content:

<!-- Start your template code here. for tipps and tools for template development, please refer to our help-section -->{{#invoke:SmwUtil|queryParserHelper}}<!--Last line of your template code--><noinclude>
{{documentation|content=This is a helper template that prepares the output of a semantic ask query so it can easily be parsed in a lua table. See [[Module:SmwUtil]] for more information.}}
<!-- Add categories to the /doc subpage, not here! -->[[Category:Query templates]][[Category:Metatemplates]][[Category:Class engine]]
</noinclude>