Help:Service links

From HackerspaceWiki
Jump to: navigation, search

SMW user manual

Introduction

Browsing interfaces

Semantic search

Selecting pages

Displaying information

Concepts

Inline queries

Inferencing

Editing

Properties and types

Custom units

Semantic templates

Service links

Semantic Web

OWL/RDF export

External tools

Importing vocabulary

Ontology import

SMW admin manual

Semantic MediaWiki can provide links to online services when printing certain data in the factbox and in property pages. For example, when an article contains a geographic coordinate, it is useful to provide links to online mapping services so that users can retrieve a map of that location with one click. Another example is to provide a link to an online currency converter for financial amounts. This page explains how you can add such features to a semantic wiki (without writing PHP code to support a new datatype).

Service links for properties[edit]

The information for additional links to online services in the factbox is associated with the property used. For example, this wiki's Property:Coordinates will show various links to online maps when it appears in the factbox, whereas other properties that also use Type:Geographic coordinate might not show this. This is crucial in many applications, since the datatype alone usually does not say much about the type of link. For example a property "IMDb number" might be used for a movie's id number at IMDb, but not every property of Type:Number should display a link to IMDb.

To make a property display service links, add the special property provides service on its page. For example, the article Property:Coordinates might include the annotation

[[provides service::online maps]]

Here, "online maps" is the name of a set of service links provided by the wiki. The next section explains how you specify these service links.

After you specify that a property provides service links, its property values in the factbox and on the property's own page will show an icon Service links icon.png that displays the service links when clicked.

Providing service links[edit]

In a nutshell, a wiki administrator puts the text specifying the appearance of service links in a special message article in the "MediaWiki" namespace named MediaWiki:Smw service service name. Continuing our example for coordinates, the text for [[provides service::online maps]] is in the message article MediaWiki:Smw service online maps.

Normally only users that have sysop (administrator) privileges in the wiki can add or edit pages in the MediaWiki namespace, hence only they can modify service links. This is a reasonable restriction for most wikis: since service links may appear in thousands of factboxes, they need to be trusted. Adding or modifying services should usually be discussed among many users before an administrator puts the change into practice.

All users, however, are free to associate properties with available services as described above.

The Mediawiki:Smw_service_service_name format[edit]

If you look at MediaWiki:Smw service online maps, though the message might be hard to read due to the long lines, its format essentially is as follows:

 label|http://someurl.com
 label text2|http://anotherurl.org
 ...

Every line contains one service link. The label is the text that users will see in the service link pop-up. After the pipe symbol '|' is the URL that the link will lead to.

In most cases, you want to provide information from the property value in the link. For example, a link to an online map service has to include the coordinates to display, and a link to a movie web site will have to include the ID of the movie. Since the exact data values are not known in advance, you use placeholders of the form $1, $2, $3, … in the URL. For example, the message text for a service link to IMDb could be:

IMDb|http://www.imdb.com/title/tt$1/

When SMW displays the service links for a property value, it substitutes the property value's information for these placeholders. In this IMDB example, a movie ID of Type:Number will replace $1 with the numeric value, and voilà, the service link for a movie links to its information on IMDB!

Since service links are typically perceived as "trusted resources," administrators must take care when formulating links, keeping in mind that users can accidentally or maliciously pass arbitrary URL-encoded strings to service link URLs in the place holders.

Information passed for each placeholder[edit]

The number and contents of the parameters that replace $1, $2, $3, … depend on the datatype of the property. For instance, a simple integer property replaces $1 with its value, whereas a geographic coordinate provides parameters for latitude, longitude, direction, and much more. In most cases, $1 is the most relevant parameter that just provides a URL-safe string version of the property value.

Type:Page
$1: URL-encoded article name (no namespace), with underscores replaced by spaces
Type:Number (and types with custom units)
$1: numerical value in English punctuation
$2: integer version of value, in English punctuation
$3: From SMW version 1.1 onwards unit, if any.
Type:String (but not Type:Text)
$1: URL-encoded string
Type:URL, Type:Annotation URI and Type:Email
$1: URL-encoded value of the URL(includes mailto: for Type:Email)
Type:Geographic coordinate
$1: latitude integer degrees
$2: longitude integer degrees
$3: latitude integer minutes
$4: longitude integer minutes
$5: latitude integer seconds
$6: longitude integer seconds,
$7: latitude direction string (N or S)
$8: longitude direction string (W or E)
$9: latitude in decimal degrees
$10: longitude in decimal degrees
$11: sign (- if south) for latitude
$12: sign (- if west) for longitude

Since geographic coordinates are so complicated, SMW includes a default message for MediaWiki:Smw service online maps — just add [[Provides service:online maps]] to any properties you have of Type:Geographic coordinate.

The other datatypes do not support service links. Many-valued properties could but do not in SMW version 1.1 (bug 14426).

Display of Property:Provides_service[edit]

When adding a service links to a property with the special property "provides service", the property page's factbox should display a link to the message article for the service. However, this feature is not working in SMW 1.0 (bug 12438).

Extended example[edit]

To illustrate the whole process of creating and using a new service, we provide an extended example, also implemented on ontoworld.org. Articles about Semantic Web vocabularies such as ow:FOAF contain information about the vocabulary's "namespace" and the online service ow:Swoogle allows users to search for background information on such namespaces. Our goal thus is to add a new "Swoogle service" to the ow:Property:Namespace that is used on the vocabularies articles.

As a first step, we edit the article ow:Property:Namespace and add the line

As an additional service, this property provides a 
[[provides service::Swoogle lookup]] of the entered namespace.

After saving, the factbox shows a link to the (still non-existing) service Swoogle lookup. Clicking this link, an administrator gets a new edit field, into which she enters

Swoogle lookup|http://swoogle.umbc.edu/index.php?option=com_frontpage&service=digest&queryType=digest_ns&searchString=$1

The link was retrieved by using Swoogle and replacing the search string (at the end of the link) with the parameter "$1".

After those changes are saved, the new service is fully functional, and each page that uses ow:Property:Namespace will show a suitable link to Swoogle. Some articles will still show the old version, if they are retrieved from cache, but after the next edit or purge, all articles will display the links as expected.