View source for Help:Adding subobjects

{{Interlanguage}}{{Parser hook
|name=&#35;subobject
|description=Create a subobject on a page
|minimum version=1.7.0
|parser function=Yes
|tag extension=No
}}
The parser function '''<code>#subobject</code>''' allows annotations made with Semantic MediaWiki to refer to objects that have their own property-value pairs just like wiki pages, but that do not actually have a page in the wiki. This can be used to "group" property-value pairs given on one page without requiring new auxiliary pages to be created. The pages containing values set with this parser function are stored with {{SpecialProperty|Has subobject}}.

{{Callout
 |This page explains how to add subobjects. See the page on [[Help:Subobjects and queries|querying subobjects]] for how to do this after you added subobjects.
 |info
}}

The parser function '''<code>#set_recurring_event</code>''' uses subobjects to store annotation values (see [[Help:Recurring events]]). 

== Syntax ==
<syntaxhighlight lang="html4strict">
{{#subobject:mysubobject
 |Has property 1=value
 |Has property 2=values|+sep=...
 |...
}}
</syntaxhighlight>

{{Callout
 |Like the <code>#set</code> parser function the <code>#subobject</code> parser function is a form of silent annotation: it adds values to properties but does not print anything to the page.
 |info
}} 

{{Callout
 |Using subobjects with [[#Anonymous identifier|anonymous identifiers]] is probably the preferred approach in most use cases.
}}

== Specifying multiple values for the same property ==
The syntax for specifying subobjects is very similar to the one used when [[Help:Setting values|setting values]]. Starting with {{Release|2.2.0}} a subobject with no valid annotation content (property-value declaration) is no longer permitted / stored.[[CiteRef::gh:smw:914]]

=== Add multiple lines ===
<syntaxhighlight lang="html4strict">
{{#subobject:mysubobject
 |Has property 1=value1
 |Has property 1=value2
 |Has property 2=value1
 ...
}}
</syntaxhighlight>

=== Add one line and separate values using a pipe ===
Starting with {{Release|1.8.0}} multiple values may be set with "<code>|</code>" as a delimiter. This does not create new restrictions on values  but provides a convenient short-cut. The following is the same as the above:
<syntaxhighlight lang="html4strict">
{{#subobject:mysubobject
 |Has property=value1|value2
 ...
}}
</syntaxhighlight>
{{Callout
 |The possibility of using pipes "<code><nowiki>|</nowiki></code>" for setting multiple values like e.g. "<code><nowiki>{{#subobject: Has property=value1|value2 }}</nowiki></code>" was deprecated starting with {{Release|3.0.0}} and will be removed in a later version. It is strongly recommended to migrate to using the "<code><nowiki>|+sep</nowiki></code>" parameter.[[CiteRef::gh:smw:1345]]
 |error
}}

=== Add one line and separate values using a named separator ===
{{Release|1.9.0}} introduces <code>|+sep=...</code> to identify the separator ([[Demo:Setting multiple values using a separator|see a demo]]):
<syntaxhighlight lang="html4strict">
{{#subobject:mysubobject
 |Has property 1=Value 1;Value 2;Value 3;Value 4|+sep=;
 |Has property 2=12+22+3+4+5+6+7+8+9+10|+sep=+
 |Has property 3=123,1234,12345,|+sep=
 |Has property 4=One,or,two,more,values|+sep
 ...
}}
</syntaxhighlight>
{{Callout
 |You must use a named separator if you want to assign multiple values for a single property, e.g. in [[mws:Extension:Page Forms/Defining forms#Multiple-instance templates|multi-instance templates]].
 |info
}}

== Specifying an identifier ==
Subobjects can have a named 'identifier'. This can be used to directly specify multiple property value combinations to a given data object.

=== Named identifier ===
This subobject adds the street address to the page as a subobject which is identified by the name <code>street address</code>:
<syntaxhighlight lang="html4strict">
{{#subobject:street address
 |street number=10
 |street name=Parks Road
 |postcode=OX1 3QD
 |city=Oxford
 |country=UK
}}
</syntaxhighlight>

A named identifier shall not contain a dot (i.e foo.bar) in the first [[smwissue:1302|five characters]], this naming scheme is reserved for extensions (starting with {{Release|2.4.0}} this convention is enforced).

{{Callout
 |Using subobjects with [[#Anonymous identifier|anonymous identifiers]] is probably the preferred approach in most use cases.
}}

=== Anonymous identifier ===
{{Release|1.8.0}} supports anonymous identifiers (hash-numbering) for objects that do not use a named identifier. If two subobject entities are identical in content (meaning they build an identical hash key) within the same page then only one entity will be stored and available for query representation.

<syntaxhighlight lang="html4strict">
{{#subobject:|
 ...
}}
</syntaxhighlight>

Identifier starting with:

* <code>_QUERY...</code> tag a query meta container
* <code>_ERR...</code> tag an error container

== Specifying a sortkey ==
{{Release|2.0.0}} introduces <code>|@sortkey=...</code> to allow to set an arbitrary sort value for a particular subobject. It will be treated case sensitive, i.e. values are stored as a "string" and will not appear (in terms of visibility) to the end-user but will be ordered as any other regular wiki page using a sortkey.

<syntaxhighlight lang="html4strict">
{{#subobject:street address
 |Street number=10
 |Street name=Parks Road
 |Postcode=OX1 3QD
 |City=Oxford
 |Country=UK
 |@sortkey=A
}}
</syntaxhighlight>

The sortkey in above example is "A".

== Conceptional notes ==
[[File:subobject-overview.png|thumb|260px|Clarifies the relationship between subject and subobject]]

=== Value declaration ===
If a subobject contains the same declarations then it is being recognized as being the same (technically a hash is produced to compare those entities) unless it describes something different (using an explicit name opposed to the auto-identifier given without an explicit name). Using a different name on a subobject embedded within the same subject creates an independent entity about something that may or may not be described by the same facts.

<pre>
{{#subobject:
 |Foo=Bar
}}
{{#subobject:
 |Foo=Bar
}}
</pre>

Both subobjects declare the same attributes while

<pre>
{{#subobject:Foo
 |Foo=Bar
}}
{{#subobject:Bar
 |Foo=Bar
}}
</pre>

are equal in its declaration to produce the same annotation but are different to the end that it represents a Subject X#Foo and the other a Subject X#Bar. Another way to create a distinctions is by using `@sortkey` (those are not equal hence treated as different entities and therefore can be queried individually):

<pre>
{{#subobject:
 |Foo=Bar
 |@sortkey=Foo
}}
{{#subobject:
 |Foo=Bar
 |@sortkey=Bar
}}
</pre>

=== Using categories ===

As of {{Release|2.3.0}}, <code>@category</code> can be used to add a category classification. While subobjects with categories can be queried as any other object, they will not appear in an individual <code>Category: ...</code> list because a subobject is a Semantic MediaWiki and not a MediaWiki concept.

<pre>
{{#subobject:
 |Has page=Example/0301/1
 |@category=ABC;123|+sep=;
}}
</pre>

Prior to {{Release|2.3.0}}, an alternative approach based solely on properties can be used: 
* Name your category-like properties as you would name a category, e.g. "Property:Detective fiction".
* Using [[Property:Subproperty of]], you can arrange these category-like properties into a deeply nested hierarchy (e.g. "Property:Detective fiction" is a member of "Property:Crime fiction" is a member of "Property:Genres", etc.). In this way, you can closely mimic a category hierarchy.
* In order to classify a subobject in this method, assign, within the subobject, any value to the property which corresponds to the desired classification. The value assigned to the property is irrelevant.
* While with a traditional category-based approach, you would query on <nowiki>[[Category:Crime fiction]]</nowiki> and retrieve only pages belonging to this category and its subcategories, you can now query on <nowiki>[[Crime fiction::+]]</nowiki> and retrieve pages as well as subobjects that belong to this property and its subproperties.

== Querying for subobjects ==
: ''Main page: [[Help:Subobjects and queries]]''

Subobjects can be treated just like pages. The simplest way to query for a set of subobjects is to ask for the existence of a property that is unique to the subobjects, e.g.
<syntaxhighlight lang="html4strict">
{{#ask:
 [[postcode::+]]
 |? street number
 |? street name
 ...
}}
</syntaxhighlight>

(assuming that all 'address' subobjects have the postcode property). For querying purposes, you can define a 'dummy' property for subobjects that you want to group together in this way, e.g. 'is address=1'.<!--- ? --->

For more information about '''subobjects and queries''', see [[Help:Subobjects and queries|here]].

== Examples ==
* [[Demo:Subobject]]
* [[Demo:Setting multiple values using a separator]]
* Issue with row values vs single values, see [[Examples/Queries/Bubble chart on aggregate numbers]]
* Understanding content modelling using subobjects, see [[Thread:Talk:Semantic Result Formats/Incorrect Sum if more than one property has same numerical value/reply (3)|Incorrect Sum if more than one property has same numerical value]]
* Clarify [[Examples/Subobject identifiers (named vs. anonymous)|subobject identifiers (named vs. anonymous)]] output characteristics

== Troubleshooting ==
; Problem with subobjects that have a '=' character in a parameter value when using a template
: See this [[smwissue:193|issue]] for a workaround.

== See also ==
* [[Help:Adding subobjects using the Page Forms extension|Adding subobjects using the Page Forms extension]]
* [[Help:Subobjects and queries|Querying subobjects]]
* [[Help:Avoiding whitespace]] when using parser functions
* Some development notes about [[Subobject handling|subobject handling]]

== References ==
<references />
<div style="display: none">
{{DEFAULTSORT:Subobject}}
{{doc.info
 |master page=Help:Adding subobjects
 |status=effective
 |progress=90
 |priority=1
 |minversion=2.3.0
}}
</div>