Documentation

SemanticLinks Plugin

QuerySearch? backlinks, and populate ad-hoc metadata using [[Property::Value]] Semantic MediaWiki syntax

SemanticLinks Plugin

PreferenceSettings

Enable rendering: `RENDERING`

Rendering of links is enabled by default, but can add unwanted CPU overhead. You may wish to disable the rendering by default (in SitePreferences), and then only enable on webs where it's needed in these web's WebPreferences topics.

Example:

   * Set SEMANTICLINKSPLUGIN_RENDERING = on

Default web for property topics: `DEFAULT_PROPERTYWEB`

Example:

   * Set SEMANTICLINKSPLUGIN_DEFAULT_PROPERTYWEB = Applications/SemanticProperties

See #AboutDEFAULTPROPERTYWEB

Semantic links - syntax

Use the following link syntax to create a special 'semantic' link. Semantic links are rendered using templates (see #Templates) but also populate special metadata (META:SLPROPERTY, see #Meta_Data).

Note	Example	Preview	#
Semantic link	[[IsPartOf::UserDocumentationCategory]]	IsPartOf::UserDocumentationCategory?
Semantic link with Foswiki-style link text	[[IsPartOf::UserDocumentationCategory][docs]]	docs?
Semantic link with SMW-style link text	[[IsPartOf::UserDocumentationCategory\|docs]]	[[IsPartOf::UserDocumentationCategory	docs]]
Non-semantic link	[[:IsPartOf::UserDocumentationCategory][docs]]	docs?

Templates

When rendering a link, SemanticLinksPlugin travels a slightly different skin path to that of the standard templates path? . The path used, and the name of the DEFs that are loaded are based on the property name used in the semantic link. The order looks like this:

First, use the standard skin path? to get DEFs named in the form of SemanticLinksPlugin::PROPERTYNAME::Link. This gives skin templates a chance to target only links using a specific property name. You might do this if your RDF needs to use multiple ontologies, or you can't easily transform property names consistently into RDF.
If the property name matches the name of a topic that exists, load template directives from it and try DEFs named of the form:
1. SemanticLinksPlugin::%SEMANTICLINKSPLUGIN_TMPL%::Link, where SEMANTICLINKSPLUGIN_TMPL is either a URL parameter? or PreferenceSetting.
2. SemanticLinksPlugin::Link
Finally, use the standard skin path? to find DEFs named in the form of SemanticLinksPlugin::Link. Unless you override them with your own skin or AutoViewTemplatePlugin? templates, these will come from templates/semanticlinksplugin.tmpl.

DEFs

TMPL:DEF{...}	Description
`SemanticLinksPlugin::Link`	Build markup for an `[[ordinary::link]]`
`SemanticLinksPlugin::LinkWithtext`	Build markup for a `[[link::with][text]]`
`SemanticLinksPlugin::MissingLink`	Build markup for an `[[ordinary::link]]` to a non-existant topic
`SemanticLinksPlugin::MissingLinkWithtext`	Build markup for a `[[link::with][text]]` to a non-existant topic

Tokens

Given a link of the form:

[[Example.Property::UserDocumentationCategory?query=part#AnchorPart][Example text]]

Preview:

Example text?

These tokens apply:

Token	Example	Description
`$text`	Example text	text part of the link
`$property`	Example.Property	Property part (LHS of '::')
`$property(web)`	Example	Web part of the property
`$property(topic)`	Property	Topic part of the property
`$property(seq)`	3	Values are counted against properties, starting from 1. Property name + sequence no. forms the unique name for each `META:SLVALUE`. Same as `META:SLVALUE.propertyseq`
`$value`	System.UserDocumentationCategory?query=part#AnchorPart	Value part (RHS of '::')
`$value(web)`	System	Web part of the value
`$value(topic)`	UserDocumentationCategory	Topic part of the value
`$value(query)`	query=part	Query part of the value
`$value(qquery)`	?query=part	Query part, prefixed with '?'
`$value(anchor)`	AnchorPart	Anchor part of the value
`$value(aanchor)`	#AnchorPart	Anchor part, prefixed with '#'

Example: Default DEFs overridden from property topic

In accordance with the template path rules described above, the link below will be rendered using the SemanticLinksPlugin::LinkWithText TMPL:DEF contained within System.SemanticIsPartOf? .

[[SemanticIsPartOf::UserDocumentationCategory?query=something#anchor][Example text]]

Preview:

Example text?

Example: RDF output using named template from property topic

SemanticLinksPlugin::MyRDF::LinkWithText used from the property topic

[[System.SemanticIsPartOf::System.UserDocumentationCategory][User documentation]]

Previews:

Best viewed in Firefox:
- Click to see RDF view
Alternate:
- Click to see RDF in plain-text

Example: RDF output using overrides from a custom skin

SemanticLinksPlugin::System.SemanticIsPartOf::LinkWithText used from the templates/view.semanticlinksplugindcdemo.tmpl file

[[System.SemanticIsPartOf::System.UserDocumentationCategory][User documentation]]

Previews:

Best viewed in Firefox:
- Click to see RDF view
Alternate:
- Click to see RDF in plain-text

If you were to pass the resulting RDF to http://www.w3.org/RDF/Validator/, it should be able to plot a graph with the generated RDF similar to: RDF graph of properties for %TOPIC% topic

RDF graph of properties for %TOPIC% topic

Special properties of property topics

`SEMANTICLINKSPLUGIN_DEFAULT_VALUEWEB` PreferenceSettings

These PreferenceSettings, which may be set on the property topic specify the default web which is assumed when the value or property parts of the semantic link are topic names only, without any web prefix (i.e. are not fully-qualified topic addresses).

Consider a property topic named Cite, which is used to cite a bibliography reference topic in some text which refers to it. The user types:

[[Cite::Duke2006b]]

This will only work if the bibliography topic Duke2006b exists in the same web as the topic making the reference. However, it's usually desirable to have a dedicated web for holding bibliography topics, but then the user would have to type:

[[Cite::MyProject/Bibliography.Duke2006b]]

This can be solved by adding a SEMANTICLINKSPLUGIN_DEFAULT_VALUEWEB preference on the Cite topic, as follows:

   * Set SEMANTICLINKSPLUGIN_DEFAULT_VALUEWEB = MyProject/Bibliography

With this in place, bibliography topics can exist in a dedicated subweb, and the user can still write

[[Cite::Duke2006b]]

to access them.

`SEMANTICLINKSPLUGIN_DEFAULT_PROPERTYWEB` PreferenceSettings

Similarly, you may collect useful property topics into a common web which can be shared throughout your wiki by setting

   * Set SEMANTICLINKSPLUGIN_DEFAULT_PROPERTYWEB = Applications/SemanticProperties

in Main.SitePreferences

With this setting, and the Cite property topic stored in Applications/SemanticProperties web, you may use

[[Cite::...]]

from anywhere in the wiki.

Meta Data

Frogs [[Eat::Flies][eat flies]], [[Eat::Mosquitos][mosquitos]]
and are [[PreyOf::Snakes][preyed on by snakes]].

on save, gives:

 %META:SLPROPERTY{name="Eat"    num="2"}%
 %META:SLVALUE{   name="Eat__2"      property="Eat"      propertyaddress="System.Eat"      propertyseq="2" propertyweb="System" value="Mosquitos" valueaddress="System.Mosquitos" valuetopic="Mosquitos" valueweb="System"}%
 %META:SLVALUE{   name="Eat__1"      property="Eat"      propertyaddress="System.Eat"      propertyseq="2" propertyweb="System" value="Flies"     valueaddress="System.Flies"     valuetopic="Flies"     valueweb="System"}%
 %META:SLPROPERTY{name="PreyOf" num="1"}%
 %META:SLVALUE{   name="PreyOf__1"   property="PreyOf"   propertyaddress="System.PreyOf"   propertyseq="1" propertyweb="System" value="Snakes"    valueaddress="System.Snakes"    valuetopic="Snakes"    valueweb="System"}%
 %META:SLVALUE{   name="IsPartOf__1" property="IsPartOf" propertyaddress="System.IsPartOf" propertyseq="1" propertyweb="System" value="UserDocumentationCategory" valueaddress="System.UserDocumentationCategory" valuetopic="UserDocumentationCategory" valueweb="System"}%

A complete list of properties on a given topic may be obtained using:

%QUERY{"slproperties.name"}%

Preview:

A complete list of values for a given property may be obtained using:

%QUERY{"slvalues[property='Eat'].value"}%

Preview:

And all values of all properties on the current topic could be rendered using:

%FORMAT{
  "%QUERY{"slproperties.name"}%"
  type="string"
  format="$percentFORMAT{
    \"$percentQUERY{\"slvalues[property='$item'].value\"}$percent\"
    type=\"topic\"
    header=\"   * $item$n\"
    format=\"      * [[$dollarweb.$dollartopic][$dollartopic]] created $dollarcreatedate\"
  }$percent"
}%

Preview:

QuerySearch backlinks

When SemanticLinksPlugin is enabled, topics are saved with META:LINK MetaData containing (almost) all links contained in the topic content. The schema is as follows:

type: META:LINK
alias: links
keys:
- name - numeric index, in order of appearance in the topic content
- address - the (absolute) path in the link
- scope - internal or external
- type - autolink, semantic or bracket
- web, topic - for links of internal scope only

Notes

SemanticLinksPlugin avoids duplicate addresses appearing in META:LINK.
SemanticLinksPlugin tries to capture links that would normally be rendered by Foswiki, including WikiWords and ACRONYM topics.
SemanticLinksPlugin expands non-parameterised preferences variables only (I.E. Macros? are ignored) before storing the link address. For example, on this topic, a link to %WEB%.%TOPIC% will be stored as Extensions/Testing.SemanticLinksPlugin.

Example MetaData?

WebPreferences (or %WEBPREFSTOPIC%) produces:
   * %META:LINK{name="1" scope="internal" type="autolink" web="System" topic="WebPreferences"   address="System.WebPreferences"}%
[[PreyOf::Snakes]] produces:
   * %META:LINK{name="2" scope="internal" type="semantic" web="System" topic="Snakes"           address="System.Snakes"}%
[[SemanticIsPartOf]] produces:
   * %META:LINK{name="3" scope="internal" type="bracket"  web="System" topic="SemanticIsPartOf" address="System.SemanticIsPartOf"}%
http://foswiki.org/Support/SemanticLinksPlugin produces:
   * %META:LINK{name="4" scope="external" type="autolink" address="http://foswiki.org/Support/SemanticLinksPlugin"}%
[[http://www.w3.org/RDF/Validator/]] produces:
   * %META:LINK{name="5" scope="external" type="bracket"  address="http://www.w3.org/RDF/Validator/"}%

Example backlinks SEARCH

%SEARCH{
  "links[address='%WEB%.%TOPIC%']"
  type="query"
  web="%SYSTEMWEB%"
  header="Topics that link to %WEB%.%TOPIC%:"
}%

Example list of links out on a topic

<noautolink>
   * Links to other topics: %FORMAT{
      "%QUERY{"links[scope='internal'].name"}%"
      type="string"
      header="$n"
      format="      * =$percntQUERY{\"links[name='$item'].address\"}$percnt= - $percntQUERY{\"links[name='$item'].type\"}$percnt link"
   }%
   * External links: %FORMAT{
      "%QUERY{"links[scope='external'].name"}%"
      type="string"
      header="$n"
      format="      * =$percntQUERY{\"links[name='$item'].address\"}$percnt= - $percntQUERY{\"links[name='$item'].type\"}$percnt link"
   }%
</noautolink>

Preview:

Links to other topics:
External links:

REST Script (updating topics)

If you had content using a 1.x version of SemanticLinksPlugin, or you've added semantic links "off line" by modifying your Foswiki installation's topic.txt files externally, you may use the rest script to re-save topics making use of semantic links across one or more webs. The available options are:

updateweb - the web to update. all updates all webs.
updatetopic - the topic to update. If omitted, updates all topics.
recurse - on or off. Recurse into subwebs.

REST script via web browser

The URL to use is of the form: /bin/rest/SemanticLinksPlugin/reparse?updateweb=System

REST script via command line

It may be unreasonable to run the rest script via web browser if you have any non-trivial amount of data, so on a production system it's best to invoke the rest script from the command line where the process won't be affected by timemouts and webserver restarts. The following examples assume:

Your web server user is www-data (default on Debian systems)
The path to the root of your Foswiki installation is /path/to/foswiki

Error: no such plugin chili

cd /path/to/foswiki
sudo -u www-data bin/./rest /SemanticLinksPlugin/reparse -updateweb System

TODO

The example templates are kind of lame...
Ship with an interesting set of example topics
Ship an example that abuses the templating feature to do interesting linked-data ajax things with semantic links, Eg. [[ISBN::2134567]] could have a template in the ISBN property topic which renders some specially styled <span> tag to enable some jquery code to go out and resolve the ISBN into publisher, author, book title... in the browser.

Known Issues

For now, values are expected to be internal links to other topics
Sanitisation of property/value?
No attempt to support Semantic MediaWiki's {{#set ....}} syntax at this point
[[Foo::Bar|label]] isn't understood by WysiwygPlugin, so the syntax breaks TML tables

Installation

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Author:	Foswiki:Main.PaulHarvey
Copyright:	© 2010-2011, Taxonomy Research & Information Network, Foswiki Contributors
License:	GPL (GNU General Public License)
Release:	2.3.0
Version:	13021 (2011-11-08)
Change History:
08 Nov 2011 (2.3.0)	Foswikitask:Item11243 - *Breaking compatibility* - Replaced `[[SemanticLinksPlugin_DEFAULTWEB::...]]` notation with `SEMANTICLINKSPLUGIN_DEFAULT_VALUEWEB` and introduced `SEMANTICLINKSPLUGIN_DEFAULT_PROPERTYWEB` PreferenceSettings
06 Jul 2011 (2.1.2)	Foswikitask:Item10913 - Fix missing init call in the reparse REST handler where, unless you only reparse an individual topic, pollutes topics with lots of bogus properties/values/links
17 Jun 2011 (2.1.1)	Foswikitask:Item10887 - Fix incorrect propertyseq values
16 Jun 2011 (2.1.0)	Foswikitask:Item10884 - Implement a 'meta-property' for property topics to control default web context on links only containing a topic name - Removed `META:SLPROPERTY.values` key. Query `META:SLVALUE.value` instead. - Renamed `META:SLVALUE.anchor` key to `META:SLVALUE.fragment`. - Removed `META:SLVALUE.query` and `META:SLVALUE.text` keys. - `META:SLPROPERTY.name` key is now always the topic part only. Web prefixes are stripped. - Added `valueweb`, `valuetopic`, `valueaddress`, `propertyweb`, `propertytopic`, `propertyaddress` keys to `META:SLVALUE` type.
10 May 2011 (2.0.1)	Foswikitask:Item9961 - Implement `$property(seq)` token & documented
07 May 2011 (2.0.0)	Foswikitask:Item9961 - *Breaking compatibility* - Deleted `META:SLPROPERTIES`. Use `%QUERY{"slproperties.name"}%` for a list of property names - Renamed `META:SLPROPERTYVALUE` to `META:SLVALUE`. Use the rest script to update your topics. - Renamed `slpropertyvalue` and `slproperty` to `slvalues` and `slproperties`. You will need to re-write your queries! - Changed template tokens from `$valuefoo` to `$value(foo)` format - Added `META:LINK` metadata to allow QuerySearch? of topic backlinks - Added a rest script to support bulk updating topics with backlink `META` and the new `META:SL...` schema
06 May 2011 (1.2.0)	Foswikitask:Item9961 - Fix always saving an SLPROPERTIES even when no semantic links present; re-work token parser
06 Jan 2011 (1.1.0)	Foswikitask:Item9961 - Rename SEMANTICLINKSPLUGIN_ENABLED to SEMANTICLINKSPLUGIN_RENDER; default to on
05 Nov 2010 (1.0.3)	Foswikitask:Item9948 - Fix registerMETA bug, QUERY examples; fix template bug
03 Nov 2010 (1.0.0)	Foswikitask:Item9897 - Initial version
Home:	http://foswiki.org/Extensions/SemanticLinksPlugin
Support:	http://foswiki.org/Support/SemanticLinksPlugin

PackageForm edit

ExtensionClassification	Information structuring and Search
ExtensionType	PluginPackage
ImageUrl
DemoUrl	http://trin.org.au/System/SemanticLinksPlugin
SupportUrl	SemanticLinksPlugin
DevelopedInSVN	Yes
ModificationPolicy	PleaseFeelFreeToModify

Support

Ask a new question

Can't find your problem here, or would you like to post a request? Ask a question on SemanticLinksPlugin.

Bug Tracker

Active Items

Id	Summary	Priority	Current State	Creation Date	Last Edit
Item11241	Nested properties in the SemanticLinksPlugin are not saved on a per-link basis and it does not provide a unique identifier for querying link meta-data	Normal	New	06 Nov 2011 - 12:47	06 Nov 2011 - 12:47
Item10942	Nested attributes feature: metadata handling	Enhancement	Being Worked On	05 Jul 2011 - 14:55	15 Mar 2012 - 23:44

Discussion

SemanticLinksPlugin Development

This is the topic to discuss development of

SemanticLinksPlugin?

On this page:

Ask a new question
Active Items
Active Items
Discussion

If you need support, go to Support.SemanticLinksPlugin where you can ask questions and find answers to previously asked questions.

If you want to report a bug, or a feature request, go to Tasks.SemanticLinksPlugin where you can see already submitted issues and where you can submit a new bug report or feature request.

Active Items

Id	Summary	Priority	Current State	Creation Date	Last Edit
Item11241	Nested properties in the SemanticLinksPlugin are not saved on a per-link basis and it does not provide a unique identifier for querying link meta-data	Normal	New	06 Nov 2011 - 12:47	06 Nov 2011 - 12:47
Item10942	Nested attributes feature: metadata handling	Enhancement	Being Worked On	05 Jul 2011 - 14:55	15 Mar 2012 - 23:44

Discussion

To discuss development of this extensions please go to Development.SemanticLinksPlugin.

Download

Topic attachments
I	Attachment	Action	Size	Date	Who
md5	SemanticLinksPlugin.md5	manage	0.2 K	08 Nov 2011 - 12:43	PaulHarvey
sha1	SemanticLinksPlugin.sha1	manage	0.2 K	08 Nov 2011 - 12:44	PaulHarvey
tgz	SemanticLinksPlugin.tgz	manage	28.3 K	08 Nov 2011 - 12:43	PaulHarvey
zip	SemanticLinksPlugin.zip	manage	31.7 K	08 Nov 2011 - 12:43	PaulHarvey
EXT	SemanticLinksPlugin_installer	manage	4.5 K	08 Nov 2011 - 12:43	PaulHarvey
png	dcdemo.png	manage	8.7 K	03 Nov 2010 - 05:54	PaulHarvey

How to configure your Foswiki to install from this repository

Documentation

SemanticLinks Plugin

PreferenceSettings

Enable rendering: RENDERING

Default web for property topics: DEFAULT_PROPERTYWEB

Semantic links - syntax

Templates

DEFs

Tokens

Example: Default DEFs overridden from property topic

Example: RDF output using named template from property topic

Example: RDF output using overrides from a custom skin

Special properties of property topics

SEMANTICLINKSPLUGIN_DEFAULT_VALUEWEB PreferenceSettings

SEMANTICLINKSPLUGIN_DEFAULT_PROPERTYWEB PreferenceSettings

Meta Data

QuerySearch backlinks

Notes

Example MetaData?

Example backlinks SEARCH

Example list of links out on a topic

REST Script (updating topics)

REST script via web browser

REST script via command line

TODO

Known Issues

Installation

Plugin Info

PackageForm edit

Support

Ask a new question

Bug Tracker

Active Items

Discussion

SemanticLinksPlugin Development

Active Items

Discussion

Download

Enable rendering: `RENDERING`

Default web for property topics: `DEFAULT_PROPERTYWEB`

`SEMANTICLINKSPLUGIN_DEFAULT_VALUEWEB` PreferenceSettings

`SEMANTICLINKSPLUGIN_DEFAULT_PROPERTYWEB` PreferenceSettings