Extensions Wiki » Extensions » Semantic XWiki

Semantic XWiki

Last modified by Karel Gardas on 2012/11/16 22:14
cogSemantic XWiki Extension integrates XWiki with Jena semantic web framework and adds a set of semantics tags
TypeJAR
Developed by

Karel Gardas

LicenseGNU Lesser General Public License 2.1

View Source

Download

Description

Semantic XWiki Extension integrates XWiki with Jena semantic web framework and adds a set of semantics tags which are documented below.

Sponsorship

The research leading to these results has received funding from the European Union Seventh Framework Programme (FP7/2007-2013) under grant agreement No FP7-242474.

The research was also partially funded by the European Space Agengy as part of contract 4000101353 / 10 / NL / SFe

The code was written and is maintained by Karel Gardas (ObjectSecurity Ltd.). ObjectSecurity also provides Semantic XWiki Technical Support, Consulting, Training

semProp

The semProp macro is used to define sematic property. It requires one parameter value which defines the value of the property, its prefix and its name in the form of <prefix>(/|#)<name>::<value>. Please note that macro does not output anything to the page! So it is basically invisible to the target page audience. Please note that since the properties are directly associated to the page where macro is used, then the life-cycle of properties is the same like of the page. This means, if you delete the page from the xwiki, properties associated with the page are also deleted automatically.

Examples:

{{semProp value="http://purl.org/dc/elements/1.1/title::The Hobbit"/}}

defines the property title with the prefix http://purl.org/dc/elements/1.1 to value The Hobbit

{{semProp value="http://www.objectsecurity.com/bookStore#WRITTEN_BY::J.R.R.Tolkien"/}}

defines the property WRITTEN_BY with the prefix http://www.objectsecurity.com/bookStore to value J.R.R.Tolkien.

visSemProp

The visSemProp macro provides the same functionality like semProp macro, but is visible to the target audience since it outputs the property value to the page. It also consumes optional links parameter which might be set to value true or false and which defines if the output should be in a form of link or not.

Example:

The Hobbit is the fantasy book written by
{{visSemProp value="http://www.objectsecurity.com/bookStore#WRITTEN_BY::J.R.R.Tolkien" links="true"/}}
for his son Christopher.

The output of this sentence will be:

The Hobbit is the fantasy book written by J.R.R.Tolkien for his son Christopher.

where J.R.R.Tolkien will be a link to its wiki page. The visSemProp property macro supports also another two optional parameters: linkAttr and linkRes their semantic is exactly same like in the case of getSemProp macro.

semPropTab

The semPropTab macro prints all the properties for the page defined together with theirs values in a form of a table. It consumes one optional links parameter which defines if the values printed in the page should be presented as a links to their wiki pages or not.

Example:

{{semPropTab links="true"/}}

outputs following table (at least for the examples defined above):

 PropertyValue
http://www.objectsecurity.com/bookStore#WRITTEN_BYJ.R.R.Tolkien
http://purl.org/dc/elements/1.1/titleThe Hobbit

Please note that if you need more advanced links remapping functionality because default link representation is not suitable for your scenario, then you should use semQuery macro instead of simple semPropTab macro.

rmSemProp

The rmSemProp is the reverse macro to semProp. It does not define, but removes definition of the property. It consumes the same value parameter in the same format as semProp macro except the property value itself.

Example:

{{rmSemProp value="http://www.objectsecurity.com/bookStore#WRITTEN_BY"/}}

removes definition of property WRITTEN_BY with prefix http://www.objectsecurity.com/bookStore
from the page.
Please note that you should not use rmSemProp macro as the properties associated with the page are deleted automatically during the page delete. This macro is documented here for historic reason when it was really needed since automatic properties deletion was not implemented yet.

semQuery

The semQuery macro executes specified SPARQ query and outputs its output into a table of specified form or into a line. The macro takes two mandatory parameters: header which specifies header's fields divided by commas and query which specifies SPARQ query. The macro also consumes optional links parameter which specifies if the output values should be in a form of wiki links or not, optional linksAttrs parameter which specifies mapping between links values printed in the table and actual link which is used on click and optional linksValuesRemapping parameter which specifies string replacement performed on the link value. The macro also supports using <this> keyword inside the SPARQ query string. Before passing query to the SPARQ engine, <this> will be replaced by the page reference (URL). The format of macro output is specified by optional mode parameter.

Example:

{{semQuery query="SELECT ?author ?title WHERE { ?book <http://purl.org/dc/elements/1.1/title> ?title . ?book <http://www.objectsecurity.com/bookStore#BOOK> ?isBook . ?book <http://purl.org/dc/elements/1.1/creator> 'J.R.R.Tolkien' . ?book <http://purl.org/dc/elements/1.1/creator> ?author}" header="title,author" links="true"/}}

prints the table with two columns: title and author. All values will be in a form of wiki links and the value obtained are specified by the provided query query string.

Another example shows usage of linksAttrs parameter:

{{semQuery query="select ?ref ?Name where {?ref <http://www.objectsecurity.com/bookStore/book_author_name> 'J.R.R.Tolkien' . ?ref <http://www.objectsecurity.com/bookStore/book_name> ?Name}" header="Name" links="true" linksAttrs="ref>Name"/}}

it prints a table listing names of books written by J.R.R.Tolkien. It also maps ref parameter to a Name parameter link. This means, the table contains Name values, but the links are actually of ref value. This is usable when you need to have some special characters in for example name of book, but those characters cannot be used for book's resource name (URL). E.g. .../TheHobbit as a resource ref and The Hobbit (with space) as a book Name.

Another example shows usage of linksValuesRemapping parameter and <this> keyword:

{{semQuery query="select ?Author ?Book ?br where { ?ref <http://www.objectsecurity.com/bookStore/author_name> ?Author . ?ref <http://www.objectsecurity.com/bookStore/author_url> '<this>' . ?br <http://www.objectsecurity.com/bookStore/book_author_name> ?Author . ?br <http://www.objectsecurity.com/bookStore/is_book> 'TRUE' . ?br <http://www.objectsecurity.com/bookStore/book_name> ?Book }" header="Book" links="true" linksAttrs="br>Book" linksValuesRemapping="http://localhost>http://silence"/}}

it prints a table listing names of books written by the author which is defined on the page from which the query is done. Links to books are remapped and their URL is changed from localhost to silence hostname. Please note that linksAttr functionality is run before linksValuesRemapping and both might be combined together like is shown in this example. Also please note usage of <this> keyword in the query string.

The mode parameter specifies the output format of the macro. If it does have value of "TABLE" then the output is table (also by default if the mode parameter is not used). If the value is "LINE", then the output is line of text with values divided by commas. Let's have a macro which output is following table:

Header 1Header 2
Value 1 Value 2
Value 3 Value 4

then if mode="LINE" optional parameter is used, then the output of such macro is:
Value 1, Value 2, Value 3, Value 4

getSemProp

The getSemProp macro prints the value of defined property to the web page. Besides mandatory value parameter which specifies the property name it also supports links, linkAttr and linkRes optional parameters. The links parameter specifies if the returned value should be in the form of link. The linkAttr parameter specifies the property name which value will be used as a link. This is useful in case the original property value is not correct link and the object also do have some other property set which provides the correct link. This is very similar to what linksAttrs parameter do in case of semQuery macro. And finally linkRes parameter specifies the value of the link directly.

Example:

{{getSemProp value="http://www.objectsecurity.com/bookStore/book_author_name" links="true" linkAttr="book_author_res"/}}

this uses linkAttr parameter and following is using linkRes parameter:

{{getSemProp value="http://www.objectsecurity.com/bookStore/book_author_name" links="true" linkRes="http://localhost:8080/xwiki-enterprise-web-3.1-SNAPSHOT/bin/view/Book+store/JRRTolkien"/}}

semPropFromCtx

The semPropFromCtx macro defines property with a given name and which value is taken from the XWiki context object. This is very useful in order to use data available in XWiki scripts and pass then into semantic web framework. Typical usage is inside the XWiki's objects sheets pages where in presentation script the data value is set into the context with some specific name and later it is taken from the context and used as a property value for the page by this macro. The macro consumes one mandatory parameter with name value. It should be provided in the form: <property name>::<xwiki context variable name>.

Example:
{{velocity}}
## You can modify this page to customize the presentation of your object.
## At first you should keep the default presentation and just save the document.

#set($class = $doc.getObject('Book store.BookClass').xWikiClass)
#foreach($prop in $class.properties)
 ; $prop.prettyName
 : $doc.display($prop.getName())
#if ($prop.prettyName == "Author name")
$xcontext.put("book_author_name_value", $doc.display($prop.getName()))
#end
#if ($prop.prettyName == "Book name")
$xcontext.put("book_name_value", $doc.display($prop.getName()))
#end
#if ($prop.prettyName == "kind")
$xcontext.put("book_kind_value", $doc.getObject('Book store.BookClass').getProperty('kind').value)
#end
#end
{{/velocity}}
{{semPropFromCtx value="http://www.objectsecurity.com/bookStore/book_author_name::book_author_name_value"/}}
{{semProp value="http://www.objectsecurity.com/bookStore/is_book::TRUE"/}}
{{semPropFromCtx value="http://www.objectsecurity.com/bookStore/book_name::book_name_value"/}}
{{semPropFromCtx value="http://www.objectsecurity.com/bookStore/book_kind::book_kind_value"/}}

this is the whole sheet code of BookClassSheet page. The BookClass defines book name and book author variables and both are set into XWiki context and later used for setting the page semantic properties. Concretely for example:

{{semPropFromCtx value="http://www.objectsecurity.com/bookStore/book_author_name::book_author_name_value"/}}

defines property of name http://www.objectsecurity.com/bookStore/book_author_name and sets its value to value associated with the XWiki context's variable book_author_name_value. Please note that for properties where you allow several values to be set (multi-select capability) you will need to get whole property ArrayList out by using for example

$doc.getObject('Book store.BookClass').getProperty('kind').value

and semPropFromCtx macro detects automatically if provided value is string or array of strings and behaves accordingly. E.g. in case of string, one property is set, in case of array, property is set for each member of the array. If you are going to use multi-select capability on SPARQ Database List property, then please make sure you check Multiple Select and Rational Storage fields while defining your class. You will also probably like to specify Multiselect separators (for editing) and Join separator (for display) attributes (just comma and space is ok there) and you are also probably going to change Display Type to either select or checkbox value. If you are going to use select, then increase value Size of the corresponding form element in edit mode to more than default 1, this is number of lines you will see from select.

Known Issues

  1. currently all macros are run equally if the page is edited and then saved or the page is just viewed. This means that for example property definition and save to the database happens always when user load the page to his/her browser. In the wide-scale deployment this would probably be performance issue and will need proper fix.
    2. properties are not automatically deleted from the page sometimes. This happens when the XWiki/Semantic Jena Web connector is not instantiated in a server. Generally speaking, before doing any edits/deletes just open in a browser at least one page which contains semantic macros. This will automatically instantiate the connector which also take cares about properties life-cycle in case of page deletes.

Additional notes

  1. All semantic properties set on page are automatically deleted when: (a) page is deleted or (b) page is saved. In case of page save properties are deleted, but when the page is opened in the browser again macros are executed and whole semantics is established again.
    2. Semantic properties might hold more than one value. Default behaviour of macros which set properties is that they modify property value. If you like to add additional property value, you need to use optional mode="ADD" parameter which is supported by all macros usable for setting the property.

Example:
{{semProp value="http://www.objectsecurity.com/requires::ARM v7" mode=ADD/}}
{{semProp value="http://www.objectsecurity.com/requires::ARM VFPv3" mode=ADD/}}
{{semProp value="http://www.objectsecurity.com/requires::ARM NEON" mode=ADD/}}

results in a page which does have three requires properties set to specified values:

PropertyValue
http://www.objectsecurity.com/requiresARM v7
http://www.objectsecurity.com/requiresARM VFPv3
http://www.objectsecurity.com/requiresARM NEON

Prerequisites & Installation Instructions

Before using semantic extensions, you will need to patch your xwiki, concretely xwiki-platform/xwiki-platform-oldcore module. Feel free to download the patch against the 4.2M2 version: xwiki-platform-oldcore-sparq-support.diff. You can also download patched jar file if you prefer this: xwiki-platform-legacy-oldcore-4.2-milestone-2.jar

Tags:
Created by Karel Gardas on 2012/10/25 21:59

Download XWiki

Get Connected