Help:Semantic Internal Objects

From Edge of Darkness Wiki

Semantic Internal Objects
Jump to: navigation, search
m (Created page with "{{Extension |Name=Semantic Internal Objects |Homepage=http://www.mediawiki.org/wiki/Extension:Semantic_Internal_Objects |Description=Setting of internal objects in Semantic Media...")
m
 
Line 1: Line 1:
-
{{Extension
+
{{TNT|Extension
-
|Name=Semantic Internal Objects
+
|name        = Semantic Internal Objects
-
|Homepage=http://www.mediawiki.org/wiki/Extension:Semantic_Internal_Objects
+
|status      = stable
-
|Description=Setting of internal objects in Semantic MediaWiki
+
|type1      = parser function
-
|Maintainer=Yaron Koren
+
|hook1      = ParserFirstCallInit
-
|First released month=August
+
|hook2      = ParserClearState
-
|First released year=2009
+
|hook3      = TitleMoveComplete
-
|Release status=stable
+
|author      = [[User:Yaron Koren|Yaron Koren]] <yaron57@gmail.com>
-
|Development status=active
+
|image      =
-
|Area of usage=Storing additional data
+
|version    = 0.8.1
-
|Associated with=SMW, SB
+
|update      = July 2014
-
|Shortcut=SIO
+
|mediawiki   = 1.17 or greater
 +
|license    = GPL-2.0+
 +
|download    = {{TNT|WikimediaDownload|SemanticInternalObjects}}
 +
[[#Download|See here]]
 +
|needs-updatephp = No
 +
|changelog  =
 +
|description = Defines a parser function, #set_internal, that is used to define "internal objects" or "n-ary relations" within Semantic MediaWiki
 +
|parameters  =
 +
|rights      =
 +
|example    =
 +
|pagedrive1  = true
}}
}}
-
'''Semantic Internal Objects''' (SIO) is an extension to [[Semantic MediaWiki]] (SMW). It provides two parser functions, <code>#set_internal</code> and <code>#set_internal_recurring_event</code>, both of which are used to define so-called "internal objects" (now "subobjects") within the Semantic MediaWiki system. SIO's main contribution to SMW is in the introduction of certain compound types of information, sometimes known as '[[Help:Type Record|n-ary relations]]', which ensures that pages can include more than one group of associated property-value pairs. SIO lets you define a two-dimensional table of information on a single page, with a call to <code>#set_internal</code> or <code>#set_internal_recurring_event</code> being used to store each row.
 
-
This functionality has been adopted by SMW so that <code>#set_internal</code> and <code>#set_internal_recurring_event</code> are now broadly equivalent to SMW's own parser functions [[Help:Adding subobjects|<code>#subobject</code>]] (introduced in SMW 1.7) and [[Help:Recurring_events|<code>#set_recurring_event</code>]] (since SMW 1.9) respectively, both of which are used to define "subobjects". Since SIO 0.7, the differences have become even less significant as SIO's parser functions now serve as a wrapper for SMW subobjects, which are called internally with SMWSQLStore3.  
+
'''Semantic Internal Objects''' is an extension to MediaWiki, that works in conjunction with [[Extension:Semantic MediaWiki|Semantic MediaWiki]]. It provides two parser functions, '#set_internal' and '#set_internal_recurring_event', both of which are used to define "internal objects" within the Semantic MediaWiki system. These are compound types of information, sometimes known as 'n-ary relations', that involve more than one data value associated together. Semantic Internal Objects lets you define a two-dimensional table of information on a single page, with a call to #set_internal being used to store each row.  
-
==Historical outline==
+
A simple example is in a cooking recipe: a recipe may call for 1 cup of flour, and the values "1", "cup" and "flour" must be encoded together - by themselves, the values are not meaningful (the third value has meaning, though not all of the meaning it could have).
-
<!--- vis-à-vis SMW --->
+
-
* The functionality of parser function <code>#set_internal</code> was introduced into SMW core with parser function [[Help:Adding subobjects|<code>#subobject</code>]] in version [[SMW_1.7.0#Native_subobjects|1.7.0]] .
+
-
* The functionality of parser function <code>#set_internal_recurring_event</code> was applied to <code>#set_recurring_event</code> in SMW 1.9.
+
-
* As of v0.7, SMW subobjects are called when using SMWSQLStore3 (for SMW 1.8+).
+
-
== <tt>#set_internal_recurring_event</tt> ==
+
Such compound information can also be stored via SMW itself. How and whether you should, though, depends on which version of SMW you're using:
-
SIO's <code>#set_internal_recurring_event</code> was created as a solution to a problem with <code>#set_recurring_event</code>: in versions of SMW prior to 1.9, <code>#set_recurring_event</code> allows you to store recurrent events but individual instances of an event can't be (easily) separated from one another. SIO defines a separate "internal object" for each instance of an event, with a different date for each, and so allows for more precise querying and display of only those event instances that fall within a certain date range. As of SMW 1.9, however, SMW's <code>#set_recurring_event</code> adopts a similar approach by defining a separate subobject for each instance of an event. The two parser functions behave alike and they both allow you to separate individual instances of an event.
+
* For versions 1.5 and 1.6 of SMW, [http://semantic-mediawiki.org/wiki/Help:Type_Record the "Record" type] offered the ability to store compound information in a single value. Though the Record type still exists, it has major problems in flexibility and queriability, and should simply be avoided.
 +
* For SMW 1.7, [http://semantic-mediawiki.org/wiki/Help:Adding_subobjects subobjects] also exist. However, they lack the ability to be called without a name, which makes them unusable in the standard way they're called, which is as part of [[Extension:Semantic Forms/Defining forms#Multiple-instance_templates|multiple-instance templates]], via the [[Extension:Semantic Forms|Semantic Forms]] extension. Again, SIO has no real alternative.
 +
* For SMW 1.8, subobjects can be called without a name, which means that they can be used in a very similar manner to SIO. In fact, if you're using SMWSQLStore3, which was added in SMW 1.8, #set_internal and #set_internal_recurring_event both simply call #subobject to store their data, making SIO a sort of alias around subobjects.
 +
* For SMW 1.9 and higher, the SMW function #set_recurring_event itself uses subobjects, which means that there is no longer any advantage, in terms of the data structure, to using the Semantic Internal Objects extension. However, the syntax of SIO's parser functions may still be preferable to that of SMW's corresponding functions.
-
===Syntax===
+
This extension requires '''version 1.5.3''' or greater of Semantic MediaWiki.
-
The (abridged) syntax for <code>#set_internal_recurring_event</code> is:
+
-
<pre>
+
==Download==
-
{{#set_internal_recurring_event:object_to_page_property
+
You can download the Semantic Internal Objects code, in .zip format, by clicking [https://git.wikimedia.org/zip/?r=mediawiki/extensions/SemanticInternalObjects&h=1e936bd3c544e19ea435e1bb99041b8a7cb99522&format=zip here].
 +
 
 +
You can also download the code directly via Git from the MediaWiki source code repository. From a command line, call the following:
 +
 
 +
<syntaxhighlight lang="bash">
 +
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/SemanticInternalObjects.git
 +
</syntaxhighlight>
 +
 
 +
The code can be viewed online, with the full history for each file, {{git file|action=tree|project=mediawiki/extensions/SemanticInternalObjects|text=here}}.
 +
 
 +
{{TNT|SB Extension}}
 +
 
 +
==Installation==
 +
To install this extension, create a 'SemanticInternalObjects' directory (either by extracting a compressed file or downloading via Git), and place this directory within the main MediaWiki 'extensions' directory. Then, in the file 'LocalSettings.php', somewhere below the inclusion of Semantic MediaWiki (both the main 'include_once' line and the 'enableSemantics' line), add the following line:
 +
 
 +
<syntaxhighlight lang="php">
 +
include_once("$IP/extensions/SemanticInternalObjects/SemanticInternalObjects.php");
 +
</syntaxhighlight>
 +
 
 +
==Usage==
 +
The syntax of #set_internal is as follows:
 +
 
 +
<pre><nowiki>{{#set_internal:object_to_page_property
 +
|property1=value1
 +
|property2=value2
 +
...
 +
}}</nowiki></pre>
 +
 
 +
It is very important to note that the first argument is a property pointing '''from''' the object, '''to''' the page, and not the other way around! This is a bit counter-intuitive, but it makes meaningful querying possible. (To follow the recipe example above, the value of ''object_to_page_property'' could be "Part of recipe", but not "Has ingredient".)
 +
 
 +
A sample call to #set_internal would be:
 +
 
 +
<pre><nowiki>{{#set_internal:Part of recipe
 +
|Has quantity=1
 +
|Has unit=cup
 +
|Has ingredient=flour
 +
}}</nowiki></pre>
 +
 
 +
This call would be placed in a page for a recipe, and it would define an object that had an automatically-generated name; the name generated depends on which version of SMW is used. For SMW 1.7 and lower, internal objects in a page called "Carrot cake" would have names like "Carrot cake#001", "Carrot cake#002" etc. For SMW 1.8 and higher, such internal objects would each have the name "Carrot cake#" plus a string of random numbers and letters.
 +
 
 +
Every one of these properties, including the first one ("Part of recipe" in the example) needs to be defined on its own property page - and the first needs to be of type "Page".
 +
 
 +
It should be noted that #set_internal does not display anything to the screen; display of the values has to be handled separately (this can be done easily if the function is called from a template).
 +
 
 +
===Querying internal objects===
 +
Internal objects, once stored, can be queried as if they were wiki pages. So the following query would show a table of all the recipes that contain more than 1/2 a cup of flour, and the number of cups they contain:
 +
 
 +
<pre><nowiki>{{#ask:[[Part of recipe::+]][[Has ingredient::flour]][[Has unit::cup]][[Has quantity::>.5]]
 +
|mainlabel=-
 +
|? Part of recipe
 +
|? Has quantity
 +
}}</nowiki></pre>
 +
 
 +
Note the "mainlabel=-" parameter in the query: that hides the names of the internal objects from users, since those names are confusing and basically meaningless.
 +
 
 +
===Lists of values===
 +
You can have #set_internal store a list of values for a property, instead of just one. To do that, you just need to append "#list" to the property name, and separate the values by commas. For instance, to record, in a page called "United States", the names of all presidents and their vice-presidents, you could have calls like:
 +
<pre><nowiki>{{#set_internal:Is president of
 +
|Has name=Ulysses S. Grant
 +
|Has vice president#list=Schuyler Colfax, Henry Wilson
 +
}}</nowiki></pre>
 +
 
 +
===Creating recurring events===
 +
The [http://semantic-mediawiki.org/wiki/Help:Recurring_events #set_recurring_event] function in Semantic MediaWiki lets you set a series of date values for a single page, representing a recurring event. '''For SMW 1.9 and higher, this call works perfectly well.''' However, for earlier versions of Semantic MediaWiki, #set_recurring_event is sometimes not an ideal solution, because individual instances of the event can't be easily separated from one another. Instead, you can call #set_internal_recurring_event, which has a syntax that's a cross between #set_internal and #set_recurring_event, and defines a separate internal object for each instance of the event, with a different date for each. This allows for precise querying and display of only those event instances that fall within a certain date range.
 +
 
 +
The (abridged) syntax for #set_internal_recurring_event is:
 +
<pre><nowiki>{{#set_internal_recurring_event:object_to_page_property
...all parameters allowed by #set_recurring_event...
...all parameters allowed by #set_recurring_event...
-
}}
+
}}</nowiki></pre>
-
</pre>
+
-
===Example===
 
Here is an example of such a call, on a page that defines a recurring event:
Here is an example of such a call, on a page that defines a recurring event:
-
Using <tt>#set_internal_recurring_event</tt>
+
<pre><nowiki>{{#set_internal_recurring_event:Is instance of
-
|<pre>
+
-
{{#set_internal_recurring_event:Is instance of
+
|property=Has date
|property=Has date
-
|start=January 4, 2012
+
|start=January 4, 2010
-
|end=June 8, 2013
+
|end=June 8, 2011
|unit=week
|unit=week
|period=1
|period=1
-
}}</pre>
+
}}</nowiki></pre>
-
 
+
You could then display a table of all the events that happened in a certain week, along with their date, with the following call:
You could then display a table of all the events that happened in a certain week, along with their date, with the following call:
-
Calling for events happening in a certain week
+
<pre><nowiki>{{#ask:[[Has date::>February 1, 2010]][[Has date::<February 7, 2010]]
-
|<pre>{{#ask:[[Has date::>February 1, 2012]][[Has date::<February 7, 2012]]
+
|mainlabel=-
|mainlabel=-
|?Is instance of
|?Is instance of
|?Has date
|?Has date
-
}}</pre>
+
}}</nowiki></pre>
 +
==Known issues==
 +
''The following issues only exist when using Semantic MediaWiki with SQLStore2, i.e. before version 1.8 of SMW.''
 +
* Having more than one call to #set_internal_recurring_event in the same page sometimes causes duplicate objects to be stored.
 +
* It appears that, at least in some circumstances, all property names are required to have their first letter capitalized in the #set_internal call, for it to work correctly. (Though this is recommended practice anyway.)
-
== Known issues ==
+
==Bugs and feature requests==
-
* Having more than one call to <code>#set_internal_recurring_event</code> in the same page sometimes causes duplicate objects to be stored.
+
You can use the Semantic MediaWiki mailing list, [https://lists.sourceforge.net/lists/listinfo/semediawiki-user semediawiki-user], for questions, suggestions or bug reports about Semantic Internal Objects. If possible, please add "[SIO]" at the beginning of the subject line, to clarify the subject matter. The extension can also be discussed via IRC at irc://irc.freenode.net/#semantic-mediawiki
-
{{docinfo
+
You can also send specific code patches to Yaron Koren, at yaron57 -at- gmail.com.
-
| master page = Semantic Internal Objects
+
 
-
| master rev  = {{REVISIONID}}
+
==Authors==
-
| master link = internal
+
Semantic Internal Objects was written by [[User:Yaron Koren|Yaron Koren]], reachable at yaron57 -at- gmail.com. Important contributions were made by Jamey Wood and MWJames.
-
| status  = effective
+
 
-
| progress = 100
+
Semantic Internal Objects was initially funded by STAR Software (Shanghai) Co., Ltd., a member of the [http://www.star-group.net/ STAR Group].
-
| priority = 4
+
 
-
| category =
+
==Version history==
-
| author = Yaron Koren
+
Semantic Internal Objects is currently at version 0.8.1. See the entire [[/Version history|version history]].
-
| editor = {{REVISIONUSER}}
+
 
-
| support = Yaron Koren
+
[[Category:Semantic MediaWiki extensions]]
-
| minversion = 1.4.3
+
-
| lang = en
+
-
| desc =
+
-
| return =
+
-
| nowarn
+
-
}}
+

Latest revision as of 03:57, 30 March 2016

Template:TNT

Semantic Internal Objects is an extension to MediaWiki, that works in conjunction with Semantic MediaWiki. It provides two parser functions, '#set_internal' and '#set_internal_recurring_event', both of which are used to define "internal objects" within the Semantic MediaWiki system. These are compound types of information, sometimes known as 'n-ary relations', that involve more than one data value associated together. Semantic Internal Objects lets you define a two-dimensional table of information on a single page, with a call to #set_internal being used to store each row.

A simple example is in a cooking recipe: a recipe may call for 1 cup of flour, and the values "1", "cup" and "flour" must be encoded together - by themselves, the values are not meaningful (the third value has meaning, though not all of the meaning it could have).

Such compound information can also be stored via SMW itself. How and whether you should, though, depends on which version of SMW you're using:

This extension requires version 1.5.3 or greater of Semantic MediaWiki.

Contents

Download

You can download the Semantic Internal Objects code, in .zip format, by clicking here.

You can also download the code directly via Git from the MediaWiki source code repository. From a command line, call the following:

<syntaxhighlight lang="bash"> git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/SemanticInternalObjects.git </syntaxhighlight>

The code can be viewed online, with the full history for each file, Template:Git file.

Template:TNT

Installation

To install this extension, create a 'SemanticInternalObjects' directory (either by extracting a compressed file or downloading via Git), and place this directory within the main MediaWiki 'extensions' directory. Then, in the file 'LocalSettings.php', somewhere below the inclusion of Semantic MediaWiki (both the main 'include_once' line and the 'enableSemantics' line), add the following line:

<syntaxhighlight lang="php"> include_once("$IP/extensions/SemanticInternalObjects/SemanticInternalObjects.php"); </syntaxhighlight>

Usage

The syntax of #set_internal is as follows: 

{{#set_internal:object_to_page_property
|property1=value1
|property2=value2
...
}}

It is very important to note that the first argument is a property pointing from the object, to the page, and not the other way around! This is a bit counter-intuitive, but it makes meaningful querying possible. (To follow the recipe example above, the value of object_to_page_property could be "Part of recipe", but not "Has ingredient".)

A sample call to #set_internal would be: 

{{#set_internal:Part of recipe
|Has quantity=1
|Has unit=cup
|Has ingredient=flour
}}

This call would be placed in a page for a recipe, and it would define an object that had an automatically-generated name; the name generated depends on which version of SMW is used. For SMW 1.7 and lower, internal objects in a page called "Carrot cake" would have names like "Carrot cake#001", "Carrot cake#002" etc. For SMW 1.8 and higher, such internal objects would each have the name "Carrot cake#" plus a string of random numbers and letters.

Every one of these properties, including the first one ("Part of recipe" in the example) needs to be defined on its own property page - and the first needs to be of type "Page".

It should be noted that #set_internal does not display anything to the screen; display of the values has to be handled separately (this can be done easily if the function is called from a template).

Querying internal objects

Internal objects, once stored, can be queried as if they were wiki pages. So the following query would show a table of all the recipes that contain more than 1/2 a cup of flour, and the number of cups they contain: 

{{#ask:[[Part of recipe::+]][[Has ingredient::flour]][[Has unit::cup]][[Has quantity::>.5]]
|mainlabel=-
|? Part of recipe
|? Has quantity
}}

Note the "mainlabel=-" parameter in the query: that hides the names of the internal objects from users, since those names are confusing and basically meaningless.

Lists of values

You can have #set_internal store a list of values for a property, instead of just one. To do that, you just need to append "#list" to the property name, and separate the values by commas. For instance, to record, in a page called "United States", the names of all presidents and their vice-presidents, you could have calls like: 

{{#set_internal:Is president of
|Has name=Ulysses S. Grant
|Has vice president#list=Schuyler Colfax, Henry Wilson
}}

Creating recurring events

The #set_recurring_event function in Semantic MediaWiki lets you set a series of date values for a single page, representing a recurring event. For SMW 1.9 and higher, this call works perfectly well. However, for earlier versions of Semantic MediaWiki, #set_recurring_event is sometimes not an ideal solution, because individual instances of the event can't be easily separated from one another. Instead, you can call #set_internal_recurring_event, which has a syntax that's a cross between #set_internal and #set_recurring_event, and defines a separate internal object for each instance of the event, with a different date for each. This allows for precise querying and display of only those event instances that fall within a certain date range.

The (abridged) syntax for #set_internal_recurring_event is: 

{{#set_internal_recurring_event:object_to_page_property
...all parameters allowed by #set_recurring_event...
}}

Here is an example of such a call, on a page that defines a recurring event: 

{{#set_internal_recurring_event:Is instance of
|property=Has date
|start=January 4, 2010
|end=June 8, 2011
|unit=week
|period=1
}}

You could then display a table of all the events that happened in a certain week, along with their date, with the following call: 

{{#ask:[[Has date::>February 1, 2010]][[Has date::<February 7, 2010]]
|mainlabel=-
|?Is instance of
|?Has date
}}

Known issues

The following issues only exist when using Semantic MediaWiki with SQLStore2, i.e. before version 1.8 of SMW.

Bugs and feature requests

You can use the Semantic MediaWiki mailing list, semediawiki-user, for questions, suggestions or bug reports about Semantic Internal Objects. If possible, please add "[SIO]" at the beginning of the subject line, to clarify the subject matter. The extension can also be discussed via IRC at irc://irc.freenode.net/#semantic-mediawiki

You can also send specific code patches to Yaron Koren, at yaron57 -at- gmail.com.

Authors

Semantic Internal Objects was written by Yaron Koren, reachable at yaron57 -at- gmail.com. Important contributions were made by Jamey Wood and MWJames.

Semantic Internal Objects was initially funded by STAR Software (Shanghai) Co., Ltd., a member of the STAR Group.

Version history

Semantic Internal Objects is currently at version 0.8.1. See the entire version history.

Retrieved from "http://nwod.org/wiki/index.php/Help:Semantic_Internal_Objects"
Personal tools
Namespaces
Variants
Actions
Navigation
games
Toolbox