Difference between revisions of "Semantic MediaWiki with Property Clusters 4"
(→SMWpc Demo Example - Classes, Properties, Templates, Categories, Articles) |
m (1 revision(s)) |
(No difference)
| |
Latest revision as of 23:44, 23 March 2008
Contents
- 1 Implementation
- 2 General Purpose Templates
- 3 SMWpc: API on Object level
- 4 SMWpc: API on Class level
- 5 SMWpc: API on Category level
- 6 SMWpc: API for all Instances of a Class
- 7 SMWpc: API on Property level
- 8 SMWpc: API on Type level
- 9 SMWpc: API on Model level
- 10 SMWpc: API on Object Form level
- 11 SMW and SMWpc: List of built-in Properties, Types and Templates
- 12 SMWpc Demo Example - Classes, Properties, Templates, Categories, Articles
Implementation
While the current implementation works and can be used to test and refine the concept of Semantic MediaWiki with Property Clustering, it is not very efficient and sometimes cumbersome. The majority of the templates could and should be replaced by equivalent parser functions in a future release.
Using SMWpc on small and medium size wikis should be possible with the current implementation.
Properties are always assigned by using a template. This may look "overdesigned" in some simple cases. But it proves to be very useful because it allows to have an abstraction layer between SMW and the user interface for property assignment. The implementation of polymorph properties and checks against the class model rely on this design principle.
General Purpose Templates
For syntactic reasons it is sometimes necessary to escape the pipe character within templates. The usual way to do this is by using a template which expands to a pipe character. SMWpc for this reason uses the following templates:
SMWpc Documentation API Object
SMWpc: API on Object level
The following functions operate on object level (instance level). This means that they are applied to a a MediaWiki page which is an Instance of a SMWpc Class. See also the complete list of SMWpc interfaces.
Template:.obj is a
Declares a MediaWiki article page to be an instance of a SMWpc Class.
Syntax: {{.obj is a|<class>}}
- expects as first parameter the name of the class without the 'Class' prefix.
- generates a statment like 'Obj is a Class'
- generates a link to a page which shows inverted links, i.e. other article which have a property that points to the current object
Implementation notes
- This template sets internal variables to allow other templates faster access to the class name
- proposed syntax for a parser function: {{#object:class|<class>}}.
- This template assigns the meta property .obj is a to the object.
Template:.obj get , Template:.obj getText , Template:.obj getMy , Template:.obj getMyText
Return the value of a property.
Syntax: {{.obj get|<instance>|<property>|[<default value>]}}
or {{.obj getMy|<property>|[<default value>]}}
- The standard variant expects as first parameter the name of an instance of a class.
- The getMy-variants take the instance name from a variable named 'this' which is for example filled by a preceding call of {{.obj is a|<class>}}.
- expects as second parameter the name of a property (without "Property:")
- takes a default value as an optional third parameter. This will be delivered if the requested property is not set for the object.
- if there is no default value given and the property is not set an empty string will be returned.
- .obj get and .obj getMy return the value of the property; if its type is a page you will get a hyperlink to the page
- the Text-variants always return plain text, even if the value is of Type 'page'.
Examples
- {{.obj get|Peter|Born at}} returns '{{#vardefine:x|{{#replace:{{#ask:format=list|PeterBorn at::*}}|/^[^\]]*\]\] */|}}}}{{#var:x}}'.
- {{.obj getText|Peter|Born at}} returns '{{#vardefine:x|{{#replace:{{#ask:format=list|PeterBorn at::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}'.
- {{.obj get|Tony|Born at}} returns '{{#vardefine:x|{{#replace:{{#ask:format=list|TonyBorn at::*}}|/^[^\]]*\]\] */|}}}}{{#var:x}}'.
- {{.obj get|Tony|Born at|''unknown''}} returns '{{#vardefine:x|{{#replace:{{#ask:format=list|TonyBorn at::*}}|/^[^\]]*\]\] */|}}}}{{#var:x}}'.
- Now we set 'this' to 'Lucie' : {{#vardefine:this|Lucie}}{{#vardefine:this|Lucie}}
- {{.obj getMy|Born at}} returns '{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#var:this}}]]Born at::*}}|/^[^\]]*\]\] */|}}}}{{#var:x}}'.
Implementation notes
- This template uses an internal variable which holds the class name
- proposed syntax for a parser function: {{#object:get|<instance>|<property>|[<default value>]}}.
Template:.obj set
Assign a value to a property of the current object.
Syntax: {{.obj set|<property>|<value>|[<prefix>]}}
- assigns the value if the property is valid for the object's Type or on of its ancestors' Types.
- If the property is invalid, a wrning will be issued and no assignment is made
- If 'prefix' is a '-' the assignment will be silently made; otherwise the the assignment will be 'verbose', i.e. the value of the property will be printed; in addition the prefix will be printed before the property value. Skipping the third parameter completely will make a verbose assignment with no prefix being displayed.
Template:-
Print the argument and store its value as the 'current property'.
Syntax: {{-|<property>}}
- display the property name
- store its name as 'the current property'; successive calls of Template:+ can be used to assign a value to this property.
Implementation notes
- An internal variable called 'prop' is used to store the property. There is no such thing like a property stack.
Template:+
Assign a value to the 'current property'.
Syntax: {{+|<value>|[<prefix>]}}
- assign the value using Template:.obj set
- The second parameter is passed to 'Template:.obj set'.
Template:.obj is referenced by
Display a list of objects which have a property that points to the object. This is kind of a 'semantic what links here'.
Syntax: {{.obj is referenced by|<instance>|<class>}}
- expects an instance name
- expects a class name (without 'Class ' prefix)
Examples
{{.obj is referenced by|Bassoon|Musical Instrument}} returns {{#vardefine:self|Bassoon}}{{#ask:format=template|template=.obj is referenced by.ask|link=none|.prop refers to::Class Musical Instrument}}
Implementation notes
- This template uses an internal variable which holds the class name
- This template uses the subtemplate Template:.obj is referenced by.ask
- proposed syntax for a parser function: {{#object:get|<class>|<property>|[<default value>]}}.
SMWpc: API on Class level
The following functions operate on class level. This means that they are applied to MediaWiki pages which describe an SMWpc Class. See also the complete list of SMWpc interfaces.
Template:.class definition
Defines a class and sets its basic attributes.
Syntax: {{.class definition|<class>|color=<color>|icon=<icon>|extends=<base class>|doc=<doc>}}
- expects as first parameter the name of the class without the 'Class' prefix.
- color = an optional color (in rrggbb Notation without a leading '#'), defaults to #f7f7f7
- icon = an optional icon file name (without the Image: prefix)
- extends = an optional name of a base class (without 'Class ') from which the current class is derived
- doc = an optional text describing the semantic concept of the class
This template should only be used within a class definition article (like 'Class Foo').
Implementation notes
- It could be useful to have a 'Special:Classes' page.
- This template assigns the meta properties .class color, .class icon, .class extends and .class doc to the class.
Template:.class description
Displays a list of properties of the class. Inherited properties are 'not' included.
Syntax: {{.class description|<class>}}
- expects the name of a class without the 'Class' prefix.
Example
- get the properties specific to 'Students': {{.class description|Student|}} returns:
{{#vardefine:desc|{{#ask:mainlabel=Property|.prop describes::Class Student .prop doc::* .prop refers to::* .prop assigned by::* .prop derived from::*}}}}{{#var:desc}}
Template:.class inheritance
Print all superclasses and the direct subclasse for a class
Syntax: {{.class inheritance|<class>}}
- expects the name of a class, e.g. 'Class Foo'
Template:.class instances
Displays a list of instances of the given class, including inherited properties.
Syntax: {{.class instances|<class>|[<criteria>]}}
- expects the name of a class (or the generic symbol '...') without the 'Class' prefix.
- criteria = an optional condition which restricts the amount of instances; syntax follows #ask.
Example
- get all chess playing students: {{.class instances|Student|[[plays game::Chess]]}}
returns:
{{#ask:format=table|mainlabel=Student|.obj is a::Class Student {{#replace:{{#replace:{{#replace:{{#replace:{{#replace:{{#ask:link=none|Property:+.prop describes::Class Student}}, {{#ask:link=none|Property:+[[.prop describes::{{#vardefine:x|{{#replace:{{#ask:format=list|Class Student.class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]]}}, {{#ask:link=none|Property:+[[.prop describes::{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#vardefine:x|{{#replace:{{#ask:format=list|Class Student.class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]]}}, {{#ask:link=none|Property:+[[.prop describes::{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#vardefine:x|{{#replace:{{#ask:format=list|Class Student.class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]]}}, Template:.class properties 5|/,? [ua]nd( )/|,\1}}|/^,$/|}},|/,+ ?/|::*]³]³}}|/(Attribut|Property):/|³[³[|}}|³|}}}}
Displays a navigation aid to browse class definitions. If the currently selected class has an icon attached it will be shown. Also provides links to graphs of the model an of the meta model.
- expects as first parameter the name of a class (or the generic symbol '...') without the 'Class' prefix.
- color = the background color for the navigation bar; typically this will be the color of the current class
Template:.class references
Displays a list of properties (and their classes) which point to instances of the specified class.
Syntax: {{.class references|<class>}}
- expects the name of a class without the 'Class' prefix.
Example
- get all references to Locations: {{.class references|Location|}}
returns:
{{#vardefine:refs|{{#ask:mainlabel=Property|.prop refers to::Class Location .prop describes::* .prop assigned by::*}}}}A Location may be referenced by:
{{#var:refs}}
Implementation notes
- This template uses a sub-template Template:.class references.ask within its #ask command
Template:.class summary
Displays a summary information about the specified class:
- description
- inheritance
- properties
- references
- instances
Syntax: {{.class summary|<class>}}
- expects the name of a class without the 'Class' prefix.
Template:.class properties
Get a list of all properties for a class
Syntax: {{.class properties|<class>|[all]}}
- expects the name of a class (without the 'Class ' prefix)
- returns a comma separated string which contains the names of all properties which can be used to describe instances of that class.
- If the second parameter is 'all' the string will also contain properties attached to base classes of the specified class ('inherited properties').
Examples
- get the property list of class 'Person': {{.class properties|Person}} returns: {{#replace:{{#replace:{{#ask:link=none|Property:+.prop describes::Class Person}}|/,? [ua]nd( )/|,\1}}|/^,$/|}}
- get the property list of class 'Student' (where 'Student' is a subclass of 'Person'): {{.class properties|Student}} returns: {{#replace:{{#replace:{{#ask:link=none|Property:+.prop describes::Class Student}}|/,? [ua]nd( )/|,\1}}|/^,$/|}}
- get the property list of class 'Student' and of all its base classes: {{.class properties|Student|all}} returns: {{#replace:{{#replace:{{#ask:link=none|Property:+.prop describes::Class Student}}, {{#ask:link=none|Property:+[[.prop describes::{{#vardefine:x|{{#replace:{{#ask:format=list|Class Student.class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]]}}, {{#ask:link=none|Property:+[[.prop describes::{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#vardefine:x|{{#replace:{{#ask:format=list|Class Student.class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]]}}, {{#ask:link=none|Property:+[[.prop describes::{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#vardefine:x|{{#replace:{{#ask:format=list|Class Student.class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}]]}}, Template:.class properties 5|/,? [ua]nd( )/|,\1}}|/^,$/|}}
Implementation notes
- 'Template:.class properties' does not use recursion because MediaWiki truncates recursive template calls. Instead it uses a fixed number of sub-templates - which limits the maximum depth of the class tree to 5.
- This could be improved in a php implementation.
- The proposed syntax for an implementation as a parser function is: {{#class:properties|<class>|[all]}}.
Template:.class parents
Get the parent class(es) of a class.
Syntax: {{.class parents|<class>}}
- expects the name of a class (without the 'Class ' prefix)
- returns a string which contains a chain of hyperlinks to all superclasses of the given class.
Example
- get the superclasses of class 'Freshman': {{.class parents|Freshman}} returns: {{#vardefine:parent|{{#vardefine:x|{{#replace:{{#ask:format=list|Class Freshman.class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}}}{{#replace:{{#vardefine:parent|{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#var:parent}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}}}{{#vardefine:parent|{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#var:parent}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}}}{{#vardefine:parent|{{#vardefine:x|{{#replace:{{#ask:format=list|[[{{#var:parent}}]].class extends::*}}|/^.*\|([^\]]*)\]\] */|\1}}}}{{#var:x}}}}[[{{#var:parent}}]] → [[{{#var:parent}}]] → [[{{#var:parent}}]] → [[{{#var:parent}}]] →|/Class ([^\]]+)/|Class \1|\1}}
Implementation notes
- 'Template:.class parents' does not use recursion because MediaWiki truncates recursive template calls. Instead it uses sub-templates which limits the maximum depth of the class tree to 5.
- An implementation in php would be more efficient and could avoid this limit.
- The proposed syntax for an implementation as a parser function is: {{#class:parents|Foo}}.
SMWpc Documentation API Category
SMWpc: API on Category level
The following templates support the definition of categories in combination with SMWpc. See also the complete list of SMWpc interfaces.
Template:.cat definition
...
Syntax: {{.cat definition|...}}
- ...
Example
- ...
Implementation notes
- ...
SMWpc Documentation API Instances
SMWpc: API for all Instances of a Class
The following templates operate on the set of all instances of a SMWpc Class. See also the complete list of SMWpc interfaces.
Template:.instances list html
...
Syntax: {{.instances list html|...}}
- ...
Example
- ...
Implementation notes
- ...
Template:.instances list html (form)
...
Syntax: {{.instances list html (form)|...}}
- ...
Example
- ...
Implementation notes
- ...
Template:.instances export wiki
...
Syntax: {{.instances export wiki|...}}
- ...
Example
- ...
Implementation notes
- ...
SMWpc Documentation API Property
SMWpc: API on Property level
The following functions operate on property level. This means that they are applied to MediaWiki pages which describe an SMWpc Property. See also the complete list of SMWpc interfaces.
It is suggested to convert the mentioned properties to SMW built-in properties. Currently the templates do nothing more than just to set the properties (and supplement prefixes like 'Template:'. This may change in future. The principle of assigning properties only via templates is strictly used within SMWpc.
Template:.prop assigned by
States that the property is assigned by the specified template(s).
Syntax: {{.prop assigned by|<template>|...}}
- expects as parameters the names of templates without the 'Template:' prefix.
- each of the given templates must be able to assign the current property to the object.
Implementation notes
- This template assigns the meta property .prop assigned by to the property.
Template:.prop built-in
States that a property is integral part of SMW.
Syntax: {{.prop built-in|<text>}}
- expects as parameter an arbitrary (short) text which will be displayed.
Implementation notes
- This template assigns the meta property .prop built-in to a property.
Template:.prop derived from
States that the property is algorithmically derived from another property (of the same class).
Syntax: {{.prop derived from|<property>}}
- expects as parameter the name of the origin property (without the 'Property:' prefix).
Implementation notes
- This template assigns the meta property .prop derived from to the property.
Template:.prop describes
States that this property can be used to describe instances of the given class(es).
Syntax: {{.prop describes|<class>|...}}
- expects as parameters the names of classes without the 'Class' prefix.
- Inheritance is respected. It is not necessary to repeat the '.prop describes' for derived classes.
Implementation notes
- This template assigns the meta property .prop describes to the property.
Template:.prop definition
Defines a property and sets its basic attributes.
Syntax: {{.prop definition|[color=<color>]|[icon=<icon>]|doc=<doc>}}
- color = an optional color (in rrggbb Notation without a leading '#'), defaults to #f7f7f7
- icon = an optional icon file name (without the Image: prefix)
- doc = an optional text describing the semantic concept of the class; text must not exceed 255 characters.
This template should only be used within a property definition (like 'Property:Foo').
Implementation notes
- This template assigns the meta properties .prop color, .prop icon and .prop doc to the property.
Template:.prop mandatory
States that the property must be specified.
Syntax: {{.prop mandatory}}
Issues a warning if the property is never set.
Implementation notes
- NOT YET IMPLEMENTED, needs hook at the end of document processing. A simple query at the end of a document still delivers the old (former) value of a property. Thus it would still deliver a value if the property assignment was deleted when saving the document. A successive edit would be o.k. unless the property was newly assigned. Then the query would return no value when saving the document.
Template:.prop refers to
States that the property serves as a reference to instances of (another or the same) class.
Syntax: {{.prop refers to|<class>}}
- expects as parameters the names of classes without the 'Class' prefix.
- polymorph properties are supported; so you can specify '.prop refers to' more than once for a property.
Implementation notes
- This template assigns the meta property .prop refers to to the property.
Template:.prop reverse
Specifies an alternate textual representation for the property which is used for the 'opposite direction'
Syntax: {{.prop reverse|<text>}}
- text must not exceed 255 characters.
Example
- For a property named 'owns' a reasonable reverse name would be 'is owned by'.
Implementation notes
- This template assigns the meta property .prop reverse to the property.
- Currently the reverse property is shown in the model and used in the 'what links here' API (.obj is referenced by')
Template:.prop unique
States that the property must only be assigned once.
Syntax: {{.prop unique}}
Issues a warning if more than one assignment is made.
Implementation notes
- implementation sets a variable for every property assignment and uses variable names as hash; this is rather inefficient.
SMWpc: API on Type level
The following functions operate on type level. This means that they are applied to MediaWiki pages which describe an SMWpc Type. See also the complete list of SMWpc interfaces.
Template:.type built-in
States that a type is integral part of SMW. Creates a hyperlink to the official documentation of that Type.
Syntax: {{.type built-in|<text>}}
- display the text and create a hyperlink to the SMW web site.
This template must only be used within the built-in SMW Types.
Implementation notes
- This template assigns the meta property .type built-in to the type.
SMWpc: API on Model level
The following templates support the presentation of an SMWpc model, i.e. they operate on the level of all Classes and all Properties. See also the complete list of SMWpc interfaces.
Template:.model show
...
Syntax: {{.model show|...}}
- ...
Example
- ...
Implementation notes
- uses Template:.model graph
- uses Template:.model class
- uses Template:.model extends
- uses Template:.model prop
- ...
Template:.model meta show
...
Syntax: {{.model meta draw|...}}
- ...
Example
- ...
Implementation notes
SMWpc Documentation API ObjectForm
SMWpc: API on Object Form level
The following templates support the representation of an SMWpc object by a single template, i.e. they deal with formatting issues. See also the complete list of SMWpc interfaces.
Template:.form header
...
Syntax: {{.form header|...}}
- ...
Example
- ...
Implementation notes
- ...
Template:.form field
...
Syntax: {{.form field|...}}
- ...
Example
- ...
Implementation notes
- ...
SMW and SMWpc: List of built-in Properties, Types and Templates
The following table lists all wiki pages which together make up the core system of SMWpc. To download them, mark the contents of all columns and copy/paste the name list to Special:Export. Choose 'save as file' and import the resulting XML file to your wiki. Make sure that you have a working installation of Semantic MediaWiki before doing so. Otherwise you will end up in namespace problems.
SMWpc Demo Example - Classes, Properties, Templates, Categories, Articles
The following table lists all wiki pages which belong to the demo example which is provided together with SMWpc. To download them, mark the contents of all columns and copy/paste the name list to Special:Export. Choose 'save as file' and import the resulting XML file to your wiki. Make sure that you have a working installation of Semantic MediaWiki before doing so. Otherwise you will end up in namespace problems.
Extensions used
- mw:Extension:Semantic MediaWiki -- see also http://ontoworld.org/wiki/Semantic_MediaWiki
- mw:Extension:DynamicPageList
- Take DynamicPageList, Wgraph, Call and Inputbox from the Zip archive!
- mw:Extension:VariablesExtension
- mw:Extension:String
- mw:Extension:ParserFunctions
- mw:Extension:SimpleForms
