OntologyPlugin

Information about rest handlers and macros of the OntologyPlugin. You can read about the basics of the extension and miscellaneous information at OntologyContrib. Information about the included skin are supplied under OntologySkin.

ONTOLOGIES

Supported Parameters

Parameter	Description	Default
ontologies	web.topic of ontology topics	all
excludeontologies	web.topic of ontology topics which should be excluded	none
format	to be displayed with each hit	$ontology
header	put in some header	none
footer	put in some footer	none
separator	put in the separator	,
orderby	name / title	title
reverse	on / off	off

Supported format Tokens

The following formatting strings can be used with the macro parameter format:

String	Description
$ontology	Displays the topic name of the ontology.
$formfield(SomeOntologyFormfieldName)	Displays the value of the given formfield of the ontology
Standard formatting tokens	Standard FormatTokens like $n, $dollar, $percnt, etc.

Supported header and footer Tokens

You can use the standard FormatTokens in the header and footer macro parameters.

RELATIONSETS

Supported Parameters

Parameter	Description	Default
ontologies	web.topic of ontology topics	all
relationsets	web.topic of relationset topics	all
excludeontologies	web.topic of ontology topics which should be excluded	none
excluderelationsets	web.topic of relationset topics which should be excluded	none
subject	web.topic of subject topic; search only for relationsets which have existing relations with the given topic as a subject	all
object	web.topic of object topic; search only for relationsets which have existing relations with the given topic as a object	all
format	to be displayed with each hit	$relationset
header	put in some header	none
footer	put in some footer	none
separator	put in the separator	,
orderby	name / title	title
groupby	you can display the relationsets grouped by ontology with option "ontology". An empty or undefined value means: no grouping	""
$oheader	Displays a header before each ontology.
$ofooter	Displays a footer behind each ontology.
reverse	on / off	off

Supported format Tokens

The following formatting strings can be used with the macro parameter format:

String	Description
$ontology	Displays the topic name of the ontology.
$relationset	Displays the topic name of the relationset.
$formfield(SomeRelationsetFormfieldName)	Displays the value of the given formfield of the relationsets.
$oformfield(SomeOntologyFormfieldName)	Displays the value of the given formfield of the relationset.
Standard formatting tokens	Standard FormatTokens like $n, $dollar, $percnt, etc.

Supported header and footer Tokens

You can use the standard FormatTokens in the header and footer macro parameters.

RELATIONS

Supported Parameters

Parameter	Description	Default
ontologies	web.topic of ontology topics (optional; if it is defined then given input for parameters "relationsets" and "relations" won't be used).	all
relationsets	web.topic of relationset topics (optional; if it is defined then parameters "ontologies" and "relations" won't be used)	all
relations	web.topic of relation topics (optional; if it is defined then parameters "ontologies" and "relationsets" won't be used)	all
excludeontologies	web.topic of ontology topics which should be excluded	none
excluderelationsets	web.topic of relationset topics which should be excluded	none
excluderelations	TODO: web.topic of relation topics which should be excluded	none
subject	web.topic of subject topic	none
object	web.topic of object topic	none
format	to be displayed with each hit	$relation
header	Displays a header at the beginning of the full output.	none
footer	Displays a footer the end of the full output.	none
separator	Displays a separator between relations	,
orderby	name / title	title
groupby	you can display the relations in groups; available options are: "ontology" or "relationset" or "ontology, relationset". With the last option relations get grouped first by ontology and furthermore by relationset. An empty or undefined value means: no grouping	""
$oheader	Displays a header before each ontology.
$ofooter	Displays a footer behind each ontology.
$rsheader	Displays a header before each relationset.
$rsfooter	Displays a footer behind each relationset.
$ffpattern	If the formfield() in the format string contains a regex, this pattern will be used to dsiplay keys and values of the formfields of the relation	key: value
$ffseparator	If the formfield() in the format string contains a regex, $ffseparator separates each formfield (key-value pair via ffpattern). Standard formatting strings like $n can be used.
reverse	on / off	off

Supported format Tokens

The following formatting strings can be used with the macro parameter format:

String	Description
$ontology	Displays the topic name of the ontology.
$relationset	Displays the topic name of the relationset.
$relation	Displays the topic name of the relation.
$subject	Displays the topic name of the subject (of a relation).
$object	Displays the topic name of the object (of a relation).
$formfield(SomeFormfieldName)	Displays the value of the given formfield of the relation. You can use names of formfield or regular expressions like formfield(/.*/). If you want to use parenthesis you have to use $opar for "(" and $cpar for ")". See also $ffpattern and $ffseparator above.
$rsformfield(SomeRelationsetFormfieldName)	Displays the value of the given formfield of the relationset.
$oformfield(SomeOntologyFormfieldName)	Displays the value of the given formfield of the ontology.
Standard formatting tokens	Standard FormatTokens like $n, $dollar, $percnt, etc.

Supported header and footer Tokens

You can use the standard FormatTokens in the *header and *footer macro parameters. (More to come.)

ATTRIBUTESETS

Supported Parameters

Parameter	Description	Default
ontologies	web.topic of ontology topics	all
attributesets	web.topic of attributeset topics	all
excludeontologies	web.topic of ontology topics which should be excluded	none
excludeattributesets	web.topic of attributeset topics which should be excluded	none
subject	web.topic of subject topic; search only for attributesets which have existing attributes with the given topic as a subject	all
object	REALLY? web.topic of object topic; search only for attributesets which have existing attributes with the given topic as a object	all
format	to be displayed with each hit	$attributeset
header	put in some header	none
footer	put in some footer	none
separator	put in the separator	,
orderby	name / title	title
reverse	on / off	off

Supported format Tokens

The following formatting strings can be used with the macro parameter format:

String	Description
$ontology	Displays the topic name of the ontology.
$attributeset	Displays the topic name of the attributeset.
$formfield(SomeAttributesetFormfieldName)	Displays the value of the given formfield of the attributeset.
$oformfield(SomeOntologyFormfieldName)	Displays the value of the given formfield of the ontology.
Standard formatting tokens	Standard FormatTokens like $n, $dollar, $percnt, etc.

Supported header and footer Tokens

You can use the standard FormatTokens in the header and footer macro parameters.

ATTRIBUTES

Supported Parameters

Parameter	Description	Default
ontologies	web.topic of ontology topics (optional; if it is defined then given input for parameters "relationsets" and "relations" won't be used).	all
attributesets	web.topic of attributeset topics (optional; if it is defined then parameters "ontologies" and "attributes" won't be used REALLY?)	all
attributes	web.topic of attribute topics (optional; if it is defined then parameters "ontologies" and "attributesets" won't be used)	all
excludeontologies	web.topic of ontology topics which should be excluded	none
excludeattributesets	web.topic of attributeset topics which should be excluded	none
excludeattributes	TODO: web.topic of attribute topics which should be excluded	none
subject	web.topic of subject topic	none
object	web.topic of object topic	none
format	to be displayed with each hit	$attribute
header	put in some header	none
footer	put in some footer	none
separator	put in the separator	,
orderby	name / title	title
reverse	on / off	off

Supported format Tokens

The following formatting strings can be used with the macro parameter format:

String	Description
$ontology	Displays the topic name of the ontology.
$attributeset	Displays the topic name of the attributeset.
$attribute	Displays the topic name of the attribute.
$subject	Displays the topic name of the subject (of a attribute); TODO? always the element?.
$object	Displays the topic name of the object (of an attribute); TODO? always the name of the property?.
$formfield(SomeFormfieldName)	Displays the vaue of the given formfield of the attribute.
$asformfield(SomeAttributesetFormfieldName)	Displays the value of the given formfield of the attributeset.
$oformfield(SomeOntologyFormfieldName)	Displays the value of the given formfield of the ontology.
Standard formatting tokens	Standard FormatTokens like $n, $dollar, $percnt, etc.

Supported header and footer Tokens

You can use the standard FormatTokens in the header and footer macro parameters.

ELEMENTS

Supported Parameters

Parameter	Description	Default
includewebs	only elements in these webs will be included in the results	all
excludewebs	all elements in these webs will be excluded from the results	none
includeelements	web.topic; these elements will be included in the results	all
excludeelements	web.topic; these elements will be excluded from the results	none
excludeontologies	web.topic of ontology topics which should be excluded	none
format	to be displayed with each hit	$element
header	put in some header	none
footer	put in some footer	none
wheader	put in some header, which will be displayed before each web	none
wfooter	put in some footer, which will be displayed after each web	none
separator	put in the separator	,
orderby	name / title	title
groupby	web	off	off
reverse	on / off	off

Supported format Tokens

The following formatting strings can be used with the macro parameter format:

String	Description
$element	web.topic of the element.
$web	web of the element.
$topic	just the topic name without the web prefix.
$formfield(SomeElementFormfieldName)	Displays the value of the given formfield of the element
Standard formatting tokens	Standard FormatTokens like $n, $dollar, $percnt, etc.

Supported header and footer Tokens

You can use the standard FormatTokens in the header and footer macro parameters.

Rest-Handlers

create

The create rest handler is called like http://your.domain/bin/rest/OntologyPlugin/create

URL parameters can be specified with a html form. See the examples below. You can also specify the parameters directly via the URL, like:

http://your.domain/foswiki/bin/rest/OntologyPlugin/create?thing=element;name=ProjectX.LaFiestaGrande;template=OntologyApp.ElementTemplate;parent=ProjectX.WebHome

thing=element

An element

• can be used with 0-n ontologies
• can be saved in any web
• can have any form (but the form must have two formfields for a title and a description!)

Parameter	Description	Default
name	web.topic of the topic to be created	-
template	template that will be used on creation of that topic	ElementTemplate
parent	assign a parent to that topic	WebHome
e_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created element topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "e_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template. You could also use it to set topic preferences of the element topic, e.g. e_ALLOWTOPICVIEW

So if you e.g. want to create an element you could use a form like the following one:

<form method="post"  action="%SCRIPTURLPATH{rest}%/OntologyPlugin/create">
<input type="text" name="thing" value="element">
<input type="text" name="name" value="">
<input type="text" name="template" value="">
<input type="text" name="parent" value="">
<input type="text" name="e_Title" value="">
<input type="text" name="e_Description" value="">
<input type="button" value="Create Element">
</form>

thing=relation

A relation

• connects two (or more) elements.
• is part of an ontology
• is stored as a topic in the following form: TheSubject with TheSubject being a topic with two formfields which specify subject and object of the relation as web.topic names

Parameter	Description	Default
ontology	web.topic of the ontology in which the relation will be created. This topic has to be in the web Ontologies.Meta!	Ontologies.Meta.Main
subject	web.topic of the subject of the relation	Opps.OntologyPlugin
object	web.topic of the object of the relation	-
relationset	web.topic of the relationset which the created relation is element of. This topic has to be in the web of the above given ontology, e.g. TopicOfTheRelationset	ElementOf ???
template	web.topic of the template that will be used to create the relation	RelationTemplate
r_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created relation topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "r_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template. IMPORTANT & SMELL: You have to pass the subject and object additionally with the name of the subject and object formfields, e.g. if those form fields in the relation (template form) are named "Subjekt" and "Objekt", you have to pass parameters with those names (including prefix r_) and the same values as with "subject" and "object".

So if you e.g. want to create a relation you could use a form like the following one:

<form method="post"  action="%SCRIPTURLPATH{rest}%/OntologyPlugin/create">
<input type="text" name="thing" value="relation">
<input type="text" name="subject" value="">
<input type="text" name="r_Subject" value="">
<input type="text" name="object" value="">
<input type="text" name="r_Object" value="">
<input type="text" name="template" value="">
<input type="text" name="relationset" value="">
<input type="text" name="r_Title" value="">
<input type="text" name="r_Description" value="">
<input type="button" value="Create Relation">
</form>

thing=attribute

An attribute

• connects two (or more) elements, usually one subject to a property
• is part of an ontology
• is stored as a topic in the following form: Ontologies/TheOntology/As/TheAttributeset/TheObject/TheSubject with TheSubject being a topic with two formfields which specify subject and object of the attribute as web.topic names

Parameter	Description	Default
ontology	web.topic of the ontology in which the relation will be created.	Ontologies/Default
subject	web.topic of the subject of the attribute	Opps.OntologyPlugin
object	web.topic of the object of the attribute, i.e. e.g. a element "Done"	-
attributeset	web.topic of the attributeset which the created attribute is element of. This topic has to be in the web of the above given ontology, e.g. Ontologies/YourOntology/As/TopicOfTheAttributeset	Ontologies/Default/As/Is
template	web.topic of the template that will be used to create the attribute	Opps/OntologyContrib/AttributeTemplate
a_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created attribute topic, e.g. if you want to fill a formfield named "Value" then pass a parameter "a_Value". This can also be used for the formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template. IMPORTANT & SMELL: You have to pass the subject and object additionally with the name of the subject and object formfields, e.g. if those form fields in the attribute (template form) are named "Subjekt" and "Objekt", you have to pass parameters with those names (including prefix a_) and the same values as with "subject" and "object".

So if you e.g. want to create a attribute you could use a form like the following one:

<form method="post"  action="%SCRIPTURLPATH{rest}%/OntologyPlugin/create">
<input type="text" name="thing" value="attribute">
<input type="text" name="subject" value="%BASEWEB%/%BASETOPIC%">
<input type="text" name="a_Subject" value="%BASEWEB%/%BASETOPIC%">
<input type="text" name="object" value="Some/Where/SizeInCm">
<input type="text" name="a_Object" value="Some/Where/SizeInCm">
<input type="text" name="template" value="Opps/OntologyContrib/AttributeTemplate">
<input type="text" name="attributeset" value="Ontologies/Default/As/Has">
<input type="text" name="a_Title" value="">
<input type="text" name="a_Description" value="">
<input type="button" value="Create Attribute">
</form>

thing=set

A set

• is an aggregate of an element and a relation which marks the element as a set
• ...

The "set element"

• is a simple topic which can be placed anywhere
• must have some DataForm attached with at least the formfields Title and Description

The relation

• is defined by a relation "element of" (or the analogue value, you defined for this ontology) to the element "Sets" (or of the analogue value you defined for this ontology; see formfields of ontology topic)
• can be manually linked to an analogue set in the Meta ontology by e.g. defining a relation "SomeWeb/Subweb/Sets SameAs Ontologies/Meta/Sets" (or using an analogue relation you defined for your ontology)

Parameter	Description	Default
ontology	web.topic of the ontology in which the relation will be created. This topic has to be in the web Ontologies.Meta!	Ontologies.Meta.Main
name	web.topic of the "set element" topic to be created	-
elementtemplate	template that will be used on creation of that topic	SetTemplate
relationtemplate	web.topic of the template that will be used to create the relation "element of sets"	RelationTemplate
e_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created set topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "e_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template
r_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created relation topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "r_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template

thing=relationset

A relationset

• is an aggregate of an element, a relation and a "relationset web"
• is part of an ontology

The element:

• can be placed anywhere; an easy to remember location would probably be directly in the ontology web
• must have some DataForm attached with at least the formfields Title and Description

The relation:

• is defined by a relation "element of" (or the analogue value, you defined for this ontology) to the element "Relationsets" (or of the analogue value you defined for this ontology; see formfields of ontology topic)
• can be manually linked to an analogue relationset in the Meta ontology by e.g. defining a relation "Ontologies/YourOntology/YourRelationset SameAs Ontologies/Meta/SameAs" (or using an analogue relation you defined for your ontology)

The relationset web:

• is a subweb of the ontology web
• contains the relation of that relationset in a web structure like Relationset/Object/Subject with Subject being a topic

You can define DataForms and TopicTemplates for your own new relationset. The DataForm must at least have the following formfields:

• Title
• Description
• Subject
• Object

You can choose the name and additional formfields on your own.

Parameter	Description	Default
ontology	web.topic of the ontology in which the relationset will be created. This topic has to be in the web Ontologies	Ontologies/Main
name	web.topic of the topic to be created	-
elementtemplate	template that will be used on creation of that topic	Opps/OntologyContrib/RelationsetTemplate
relationtemplate	web.topic of the template that will be used to create the relation "element of relationsets"	Opps/OntologyContrib/RelationTemplate
e_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created "relationset element" topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "e_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template
r_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created "relationset relation" topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "r_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template

thing=attributeset

An attributeset

• is an aggregate of an element, a relation and a "attributeset web"
• is part of an ontology

The element:

• can be placed anywhere; an easy to remember location would probably be directly in the ontology/As web
• must have some DataForm attached with at least the formfields Title and Description

The relation:

• is defined by a relation "element of" (or the analogue value, you defined for this ontology) to the element "Attributesets" (or of the analogue value you defined for this ontology; see formfields of ontology topic)
• can be manually linked to an analogue attributeset in the Meta ontology by e.g. defining a relation "Ontologies/YourOntology/As/YourAttributeset SameAs Ontologies/Meta/As/SomeDefaultAttributeset" (or using an analogue relation you defined for your ontology)

The attributeset web:

• is a subweb of the ontology/As web
• contains the individual attributes of that attributeset in a web structure like Attributeset/Object/Subject, with Subject being a topic and usually the property

You can define DataForms and TopicTemplates for your own new attributeset. The DataForm must at least have the following formfields:

• Title
• Description
• Subject
• Object

You can choose the name and additional formfields on your own.

Parameter	Description	Default
ontology	web.topic of the ontology in which the attributeset will be created. This topic has to be in the web Ontologies	Ontologies/Default
name	web.topic of the topic to be created	-
elementtemplate	template that will be used on creation of that topic	Opps/OntologyContrib/AttributesetTemplate
relationtemplate	web.topic of the template that will be used to create the relation "element of attributesets"	Opps/OntologyContrib/RelationTemplate
e_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created "attributeset element" topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "e_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template
r_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created "relationset relation" topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "r_Group". This can also be used for the formfields for a title and a description (depends on the names you gave those formfields in your above noted ontology/template

thing=ontology

Parameter	Description	Default
name	web.topic of the ontology topic to be created	-
template	template that will be used on creation of that ontology topic	OntologyTemplate
parent	assign a parent to that ontology topic	Ontologies.Meta.Ontologies
templateweb	templateweb that will be used to create the ontology web	_empty
e_OTHERPARAMETERS	You can specify other parameters which will be used to fill formfields in the created ontology topic, e.g. if you want to fill a formfield named "Group" then pass a parameter "e_Group". This should also be used for the mandatory formfields for a title and a description (depends on the names you gave those formfields in your above noted template
o_OTHERPARAMTERS	You can specify other parameters which will be used to add preferences to the ontology web, e.g. if you set "ALLOWTOPICCHANGE" the pass a parameter "o_ALLOWTOPICCHANGE". You can use empty as a value to specify an "empty" preference. The preferences of this ontology topic will be used when webs(which?) and topics(which?) are created in this ontology!

copy

thing=element

copies an element to another element (or web)

Parameter	Description	Default
source	web.topic of the existing element	-
target	web.topic of the new element. Optional.	-
newweb	full name of the web where the new element should be copied to. If parameter 'target' is specified then the parameter 'newweb' will not be used.	-
targettitle	Title of the new element	-
targetdescription	Description of the new element	-
target_SOMEFORMFIELD	Value of SOMEFORMFIELD of the new element	-
attributes	should all attributes of the existing element be copied too?	yes
relations	should all relations of the existing element be copied too?	yes

thing=relation

copies a relation to another ontology

Parameter	Description	Default
relation	web.topic of the existing relation	-
newontology	ontology where the relation should be copied to	-

thing=attribute

copies an attribute to another ontology

Parameter	Description	Default
attribute	web.topic of the existing attribute	-
newontology	ontology where the attribute should be copied to	-

thing=set

copies a set of elements to another web

Parameter	Description	Default
set	web.topic of the existing set	-
newweb	web where the set (and its elements) should be copied to	-
elements	should all elements of the set be copied too?	yes
relations	should relations of the set itself be copied too?	yes
attributes	should attributes of the set itself be copied too?	yes
relationsofelements	should relations of the elements of the set be copied too?	yes
attributesofelements	should attributes of the elements of the set be copied too?	yes

thing=relationset

copies a relationset to another ontology

Parameter	Description	Default
relationset	web.topic of the existing relationset	-
newontology	ontology where the relationset should be copied to	-
relations	should relations of the relationset be copied too?	no

thing=attributeset

copies an attributeset to another ontology

Parameter	Description	Default
attributeset	web.topic of the existing attributeset	-
newontology	ontology where the attributeset should be copied to	-
attributes	should attributes of the attributeset be copied too?	no

thing=ontology

copies an ontology

Parameter	Description	Default
source	web.topic of the existing ontology	-
target	web.topic of the new ontology	-
targettitle	Title of the new ontology	-
targetdescription	Description of the new ontology	-
target_SOMEFORMFIELD	Value of SOMEFORMFIELD of the new ontology	-
relationsets	should relationsets of the ontology be copied too?	yes
attributesets	should attributesets of the ontology be copied too?	yes
relations	should all relations of all relationsets of the ontology be copied too?	no
attributes	should all attributes of all attributeset of the ontology be copied too?	no