Help:Array format

From semantic-mediawiki.org
Help:Array formatArray format/zh-hans
Array format
Comma-separated list, with additional outputs shown in parentheses and extra formatting options
Further Information
Provided by: Extension "Semantic Result Formats"
Added: 1.6.1
Removed: still supported
Requirements: none
Format name: array
Enabled? Indicates whether the result format is enabled by default upon installation of the respective extension. yes
Authors: Daniel A. R. Werner
Categories: misc
Table of Contents

The result format array, part of the Extension "Semantic Result Formats" extension, is used to format query results in a way most suitable for further processing by MediaWiki templates or parser functions. It is quite similar to the list format but allows more options for customization. It can either output the result as string with a variety of separators between different values, or store the result directly into an array.

Parameters[edit]

The Array format is not only useful if the Arrays extension extension is installed, it also is a good alternative to Semantic MediaWiki's default list format since it allows to specify a variety of separators and not just the separator between query output values per page (sep parameter of list format).

Default parameters are optimized for use with ArrayExtension extensions or other way of processing the output, not for machine-unfriendly eye-candy like Semantic MediaWiki's proprietary list format. This means all kinds of links and generating of needless information is disabled by default, but can be activated though.

Parameter Description Allowed values Default
pagetitle Whether to show page titles as result entries or leaving them out of the result. Aliases: titles and pagetitles. show, hide show
headers Way of displaying property names in front of property printout. Value 'show' will display them as links, 'plain' without links. A separator between the property name (header) and the actual property value of a page can be defined by headersep. show, plain, hide hide
hidegaps Whether to print requested but unavailable property and record values separated by separators or leaving them out. E.g. if properties Name, Age and Value are requested, assuming Age and Value are not given on a page, this would return something like '..., Max<PROP><PROP>, ...' without, and '..., Max, ...' with active hidegaps. none, property, record, all none
link Allows to output values as links if possible. If this is set to subject (only for Array), only the page title will be included as link. all, subject, none none
limit The maximum number of results to return (equals the maximum number of pages to display information from and the length of the array or hash if created) any number maximum *
Result Separators
Note: Also see the possibility to set the default value for result separators via LocalSettings.php
sep Separator between results per page any string ', '
propsep Separator between the requested properties per page any string <PROP>
manysep Separator between many valued property values any string <MANY>
recordsep Separator between member-values of record properties any string <RCRD>
headersep Separator between property name and the actual property value of a requested page property if headers are not set to 'hide'. By default one space ' '. Setting this to something more unique together with HashTables extension available would easily allow to create some kind of two-dimensional array/hash or hash/hash construct. any string ' '
Special Functionality
name If given and ArrayExtension is available this will create an array with the specified name (no visible output then) any string not set

* The limit for array query results is set to the maximum set in Semantic MediaWiki's $smwgQMaxInlineLimit configuration variable by default.

Configuration[edit]

There are five configuration variables to configure the default separators. They can be adjusted via LocalSettings.php if required.

$srfgArraySep 
Default value for the sep parameter. Default: ', '
$srfgArrayPropSep 
Default value for the propsep parameter. Default: '<PROP>'
$srfgArrayManySep 
Default value for the manysep parameter. Default: '<MANY>'
$srfgArrayRecordSep 
Default value for the recordsep parameter. Default: '<RCRD>'
$srfgArrayHeaderSep 
Default value for the headersep parameter. Default: ' '

Examples[edit]

These variables can be set to a normal string value or they can contain an array( 'title', (int)namespace, (array)parameters ), defining one page in the wiki. In case the later is chosen, the parsed content of this site will serve as default value. The value will only be parsed once per page rendering and shouldn't contain any very dynamic content. It is useful though to define a template which can then be used in templates processing the query result any further. Example for definition:

# Default value string '<,,,>' for 'arraysep' parameter:
$srfgArraySep = '<,,,>';

# content of 'Template:SepP' as 'propsep' default value:
$srfgArrayPropSep  = array( 'SepP', NS_TEMPLATE );

# content of 'Template:SepH' with parameters 1='abc' and val='def':
$srfgArrayHeaderSep array( 'SepH', NS_TEMPLATE, array( 1 => 'abc', 'val' => 'def' );

Issue with Special:Ask[edit]

In case any configuration variable is set to get a wiki page content as value, this will not work as expected on Special:Ask. This is because the parser is not fully running at the time the value is needed. In this case, if the query is not running in inline-mode, a fallback separator will be loaded from another configuration variable, $srfgArraySepTextualFallbacks. This is an array with the keys sep, propsep, manysep, recordsep and headersep which contain the equivalent default value from above (NOT the one set in LocalSettings.php of course). This variable can be modified in LocalSettings.php as well, though, there is no real benefit from doing so since these values are only going to be used on the semantic search spacial page anyway. One should just be aware of this to avoid confusion.

Examples[edit]

Define an Array with name arrName, one array value per page containing the page title where the property Name was found

{{#ask: [[Name::+]]
| format = array
| name = arrName
}}

Practical examples[edit]

To be added



This documentation page applies to all SMW versions from 1.6.1 to the most current version.
      Other languages: zh-hans