View source for Help:Array format

{{Result format
| format name=array
| authors=Daniel Werner
| minimum version=1.6.1
| maximum version=still supported
| further reqs=none
| component=Semantic Result Formats
| categories=misc
| description=Comma-separated list, with additional outputs shown in parentheses and extra formatting options
}}
The [[Help:Result formats|result format]] '''array''', part of the [[Extension:Semantic Result Formats|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 ''[[Help:List format|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 ==
<!-- This is an auto-generated table of parameter descriptions that displays up to date docs for the installed version of SMW. Do not attempt to modify or translate in-wiki. For more info contact User:Jeroen De Dauw {{#smwdoc:array}} -->

The Array format is not only useful if the [[Arrays|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.

{| class="wikitable" style="text-align: center;"
 ! Parameter !! Description !! Allowed values !! Default
 |-
 | style="text-align: left;" | <tt>pagetitle</tt>
 | style="text-align: left;" | Whether to show page titles as result entries or leaving them out of the result. Aliases: <tt>titles</tt> and <tt>pagetitles</tt>. 
 | <code>show</code>, <code>hide</code>
 | <code>show</code>
 |-
 | style="text-align: left;" | <tt>headers</tt>
 | style="text-align: left;" | Way of displaying property names in front of property printout. Value '<code>show</code>' will display them as links, '<code>plain</code>' without links. A separator between the property name (header) and the actual property value of a page can be defined by ''headersep''.
 | <code>show</code>, <code>plain</code>, <code>hide</code>
 | <code>hide</code>
 |-
 | style="text-align: left;" | <tt>hidegaps</tt>
 | style="text-align: left;" | 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 '<code>..., Max<PROP><PROP>, ...</code>' without, and '<code>..., Max, ...</code>' with active ''hidegaps''.
 | <code>none</code>, <code>property</code>, <code>record</code>, <code>all</code>
 | <code>none</code>
 |-
 | style="text-align: left;" | <tt>link</tt>
 | style="text-align: left;" | Allows to output values as links if possible. If this is set to <code>subject</code> (only for ''Array''), only the page title will be included as link.
 | <code>all</code>, <code>subject</code>, <code>none</code>
 | <code>none</code>
 |-
 | style="text-align: left;" | <tt>limit</tt>
 | style="text-align: left;" | 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)
 | <span style="color:grey;">''any number''</span>
 | <span style="color:grey;">''maximum''&nbsp;'''<span style="color:black;font-size:1.3em">*</span>'''</span>
 |-
 | colspan=5 style='padding:8px;text-align:left;' | '''Result Separators'''<br/><span style="font-size:0.9em">''<u>Note:</u> Also [[{{FULLPAGENAME}}#Configuration|see the possibility]] to set the default value for result separators via LocalSettings.php''</span>
 |-
 | style="text-align: left;" | <tt>sep</tt>
 | style="text-align: left;" | Separator between results per page
 | <span style="color:grey;">''any string''</span> 
 | <code>',&nbsp;'</code> <!-- ', ', no actual '&nbsp;'! -->
 |-
 | style="text-align: left;" | <tt>propsep</tt>
 | style="text-align: left;" | Separator between the requested properties per page
 | <span style="color:grey;">''any string''</span> 
 | <code><PROP></code>
 |-
 | style="text-align: left;" | <tt>manysep</tt>
 | style="text-align: left;" | Separator between many valued property values
 | <span style="color:grey;">''any string''</span>
 | <code><MANY></code>
 |-
 | style="text-align: left;" | <tt>recordsep</tt>
 | style="text-align: left;" | Separator between member-values of record properties
 | <span style="color:grey;">''any string''</span>
 | <code><RCRD></code>
 |-
 | style="text-align: left;" | <tt>headersep</tt>
 | style="text-align: left;" | Separator between property name and the actual property value of a requested page property if ''headers'' are not set to '<code>hide</code>'. By default one space '<code> </code>'. 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.
 | <span style="color:grey;">''any string''</span>
 | <code>'&nbsp;'</code>
 |-
 | colspan=5 style='padding:8px;text-align:left;' | '''Special Functionality'''
 |-
 | style="text-align: left;" | <tt>name</tt> 
 | style="text-align: left;" | If given and ArrayExtension is available this will create an array with the specified name (no visible output then)
 | <span style="color:grey;">''any string''</span>
 | <span style="color:grey;">''not set''</span>
 |}

'''<span style="color:black;font-size:1.3em">*</span>''' The limit for ''array'' query results is set to the maximum set in Semantic MediaWiki's <code>[[Help:Configuration#smwgQMaxInlineLimit|$smwgQMaxInlineLimit]]</code> configuration variable by default.

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

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

=== Examples ===
These variables can be set to a normal string value or they can contain an array( <code>'title', (int)namespace, (array)parameters</code> ), 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:

<syntaxhighlight lang="php">
# 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' );
</syntaxhighlight>

=== Issue with [[Special:Ask]] ===
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, <code>$srfgArraySepTextualFallbacks</code>. 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 ==
Define an Array with name <code>arrName</code>, one array value per page containing the page title where the property ''Name'' was found
<pre>
{{#ask: [[Name::+]]
| format = array
| name = arrName
}}
</pre>

=== Practical examples ===
''To be added''

{{DEFAULTSORTKEY:Array}}
{{docinfo
| master page = Help:Array format
| master rev  = {{REVISIONID}}
| master link = internal
| status   = effective
| progress = 100
| priority = 3
| category =
| author = Daniel Werner
| editor = {{REVISIONUSER}}
| minversion = 1.6.1
| support = Daniel Werner
| lang = en
| desc =
| return =
| nowarn
}}