cross
New Foswiki release 2.1.6 is available with important security fixes.
Sourceforge foswiki email lists being discontinued. Subscribe to the new Foswiki announce and discuss lists at MailingLists
warning This is an experimental version of SemanticLinksPlugin.

support To configure your Foswiki to install from this repository, modify the {ExtensionsRepositories} setting in your lib/LocalSite.cfg like this:
$Foswiki::cfg{ExtensionsRepositories} = 'Foswiki.org=(http://foswiki.org/Extensions/,http://foswiki.org/pub/Extensions/);Local=(http://foswiki.org/Extensions/Testing/,http://foswiki.org/pub/Extensions/Testing/)';

Read more about configuring Extension repositories

SemanticLinks Plugin

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

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 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 # Should get
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:
  1. 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.
  2. 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
  3. 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:

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: 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  #37;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:

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

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/"}%
%SEARCH{
  "links[address='%WEB%.%TOPIC%']"
  type="query"
  web="%SYSTEMWEB%"
  header="Topics that link to %WEB%.%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

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 - ALERT! Breaking compatibility
- ALERT! 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
- ALERT! Removed META:SLPROPERTY.values key. Query META:SLVALUE.value instead.
- ALERT! Renamed META:SLVALUE.anchor key to META:SLVALUE.fragment.
- ALERT! Removed META:SLVALUE.query and META:SLVALUE.text keys.
- ALERT! 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 - ALERT! Breaking compatibility
- ALERT! Deleted META:SLPROPERTIES. Use %QUERY{"slproperties.name"}% for a list of property names
- ALERT! Renamed META:SLPROPERTYVALUE to META:SLVALUE. Use the rest script to update your topics.
- ALERT! 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
Topic revision: r10 - 08 Nov 2011, PaulHarvey - This page was cached on 21 Mar 2018 - 08:03.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License