Service links

From semantic-mediawiki.org
Table of Contents

Semantic MediaWiki can provide links to online services when printing certain data in the factbox, on special page special page "Browse"Shows all properties and their values annotated to a page and on 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.

Service links for properties[edit]

The information for additional links to online services in the factbox and on special page Browse is associated with the property used. For example, this wiki's Property:Has coordinates will show various links to online maps in the factbox and on special page Browse, if it is used on a wikipage, whereas other properties that also use datatype 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" of datatype Number might be used for a movie's id number at IMDb, but not every property of datatype 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 page Property:Has 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, on special page Browse and on the property's own page will show an icon (icon for service links) that displays the service links when clicked.

As of Semantic MediaWiki 2.1.0Released on 19 January 2015 and compatible with MW 1.19.0 - 1.24.x. service links will no longer be shown within the factbox since the labeling of the link was no longer working properly.

Providing service links[edit]

In a nutshell, a wiki administrator puts the text specifying the appearance of service links in a system message article in the "MediaWiki" namespace.

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.

Name of the system message[edit]

The format for the system message is MediaWiki:Smw service service name. The part "MediaWiki:Smw service" always remains unchanged while the service name changes with every system message providing a service link.

Continuing our example for Has coordinates, the text for [[Provides service::online maps]] is in the message name MediaWiki:Smw service online maps.

Content of the system message[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 text1|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. For better comprehension, please click on "View source" at the top of the page to see the raw text of the page.

Placeholders in the system message[edit]

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, etc., 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, e.g. "0019254" to http://www.imdb.com/title/tt0019254/!

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 property of datatype number 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. The datatypes listed below support service links. All other datatypes do not support service links.

Help:Datatype "Page"
$1: URL-encoded article name (no namespace), with underscores replaced by spaces
Help:Datatype "Number"
$1: numerical value in English punctuation
$2: integer version of value, in English punctuation
$3: From SMW version 1.1 onwards unit, if any.
Help:Datatype "String" (but not Help:Datatype "Text")
$1: URL-encoded string
Help:Datatype "URL", Help:Datatype "Annotation URI"
$1: URL-encoded value of the URL
Help:Datatype "Email"
$1: URL-encoded value of the URL including mailto:
Help:Datatype "Geographic coordinates"
Note: You need Maps (formerly Semantic Maps) 0.6.5 and SMW 1.5.1 or later for this.
$1: The location in non-directional float notation.
$2: The location in directional DMS notation.
$3: The latitude in non-directional float notation.
$4: The longitude in non-directional float notation.

Since geographic coordinates are complex, a sample content for the default message MediaWiki:Smw service online maps is provided on this wiki.

Difference between Service links and External identifier[edit]

To illustrate the difference between the service links feature and datatype "External identifier"Holds a value that associates it with with a external URI for formatting, see the example on page Vienna.

Service links[edit]

For service links, the Property:Wikidata ID was set up with the special property [[Provides service::Wikidata]] Additionally, the page MediaWiki:Smw_service_wikidata specifies the link for the service. When you click on the Browse Propery link for Vienna, you can see the question mark with the service link showing up once you mouse-over it.

External identifier[edit]

The property itself was setup using datatype "External identifier"Holds a value that associates it with with a external URI for formatting (which does not have anything to do with service links). In a similar way, you have to specify the uri, this time on the property page: [[External formatter uri::https://www.wikidata.org/wiki/$1]] The result is that the value itself is clickable, but it does not lead to a page within SMW, but to Wikidata.

This example shows to possible ways to map content managed in SMW to Wikidata IDs. See also Semantic MediaWiki and Wikidata.