jOWL - Semantic Javascript Library - Documentation

jOWL is a javascript library that loads and visualizes OWL-DL documents.
The use of jOWL generally implies a two step approach:

1. Load an owl file with jOWL.load
2. Access content with jOWL() and/or visualize content by using custom made representations or any of the jOWL.UI (user Interface) components.

I also advise to get accustomed to the jQuery javascript library, upon which jOWL is built, a great foundation for building rich user interfaces with jOWL.

Functions

List of Functions in the jOWL namespace.

jOWL

Main function to access Ontology Objects. Queries a jOWL-initialized (e.g. after jOWL.load, ... has been called) owl / rdfs document for referencable ontology objects.

Parameters

resource A string matching an Ontology Object's URI (local or absolute, cfr. 'rdf:ID' or 'rdf:about'). Or a jQuery wrapped xml element (with 'rdf:ID' or 'rdf:About' reference), or null if not found.
options Optional. Configuration Object. See Below.

Options in detail

type 'class' or 'property' for additional type-checking. Most users will have no need for this.

Returns

A jOWL Ontology Object

Example

jOWL("wine");

jOWL("http://www.w3.org/TR/2003/PR-owl-guide-20031209/wine#wine");

jOWL.load

Initialize/reset jOWL with an OWL-RDFS document.

Parameters

path Relative path to the owl document (example: "data/jOWL.owl").
fn Function that is triggered when load is complete. Everything jOWL related should be specified within this function, as it ensures jOWL has been properly initialized.
options Optional. Configuration Object. See Configuration Options for a description of possible settings.

Example

var options = {locale: 'en'};

jOWL.load("mypath", function(){

//All jOWL Logic should be specified here.

}, options);

jOWL.parse

Initialize jOWL with an existing OWL DOM document or an XML String. Most users will have no need for this function. See jOWL.load instead. See jOWL.load instead.

Parameters

doc An xmlString or an xmlDocument.
options Optional. Configuration Object. See Configuration Options for a description of possible settings.

jOWL.parseRDFa = function(function, options)

Alternative to jOWL.load. Instead of loading an OWL-DL document, try to parse OWL-DL syntax from the current RDFa-embedded document instead.

Parameters

fn Function that is triggered when load is complete. Everything jOWL related should be specified within this function, as it ensures jOWL has been properly initialized.
options Optional. Configuration Object. See Configuration Options for a description of possible settings.

Example

jOWL.parseRDFa(function(){

//declare all your logic inside this function

}, options);

jOWL.toString

Returns a String representation of the OWL-RDFS document or XMl node.

Parameters

xmlNode Optional, an XML node in the owl document. If not specified, then the entire owl document will be converted to String.

Returns

String representation of the xmlNode or Document.

jOWL.permalink

Construct or Parse permanent URLs for owl:Classes. Example usage can also be seen in the source code of this page.

Without parameters

The function parses the current url for an owlClass (=URI) argument.

The matching ontology object

//for a given document URL: http://jowl.ontologyonline.org/documentation.html?owlClass=DataObjects
var urlreference = jOWL.permalink();
alert(urlreference.URI);

Parameters

entry Construct an URL (permalink) for the given jOWL Object.

A newly constructed URL (as String).

var newURL = jOWL.permalink(jOWL('DataObjects')); 
alert(newURL == http://jowl.ontologyonline.org/documentation.html?owlClass=DataObjects);

jOWL.SPARQL_DL

Prepares an Object to run SPARQL-DL queries on jOWL. This section lists the javascript functions and parameters, for an overview of the query possibilities: see the SPARQL-DL page

Parameters

syntax The query, SPARQL-DL abstract query syntax that should be evaluated.
parameters Optional. An object listing pre-defined parameters, that are to be pre-filled in in the query.
options Optional configuration Object.

Examples

jOWL.SPARQL_DL("Type(?x, class)", {"class" : someClass>})

Executing the Query

The query will be executed by calling the execute function.

execute

options Same options as above can also be specified on execute instead.

new jOWL.SPARQL_DL("Type(?x, wine)")
	.execute({onComplete: function(results){ 
		arr = results.jOWLArray("?x");
}

Anatomy of the result object

object.error If an error occurred, this is where the error message is listed.
object.results Associative array containing variable to jOWLObject mappings.
object.assert True, false or undefined. Indicates whether the query evaluated to true or not. See examples above.
object.jOWLArray Function, pass a variable (e.g. ?x) as argument, it will return a jOWL.Ontology.Array containing all jOWL objects mapped to the variable.

[
{"?x" : jOWLObject, "?y" : jOWLObject},
{"?x" : jOWLObject, "?y", jOWLObject}
]

Data Objects

jOWL.Ontology.Thing

These Functions and Properties are shared by all Ontology Elements. Referencable Ontology Objects are accessed with the jOWL function.

Properties

jOWL jOWL Version.
isAnonymous true/false.
baseURI Namespace the object belongs to.
name local Name of the object.
URI local Name (+ URI if Namespace is not the same as the base Namespace), unique.
jnode jQuery wrapped xml element.

Functions

description

An Array of Strings, the content of all "rdfs:comments" specified for this object.

Tip: Use CDATA tags to keep HTML markup in your comments:

<rdfs:comment><![CDATA[
this is a <b>description</b>.
]]></rdfs:comment>

label

A human-readable representation name for this object. If jOWL.options.locale is specified then it will try to match the label against that preferred language.

jOWL('someclass').label();

annotations

terms

bind

Will map the current jOWL object to the given HTML element, for visualisation purposes.

jqelem A jQuery wrapped HTML element.

The jQuery wrapped HTML element.

jOWL('someclass').bind($(someHTMLElement));

jOWL Utility Objects

jOWL.Ontology.Class

jOWL equivalent to an owl:Class.

Extends (inherits all properties and functions) jOWL.Ontology.Thing

Properties

isClass true.

Functions

parents

A jOWL.Ontology.Array containing this class' direct parents.

children

A jOWL.Ontology.Array containing this class' direct children.

descendants

level Optional, maximum depth to fetch children, default 5.

A jOWL.Ontology.Array containing this class' descendants.

hierarchy

Constructs the entire hierarchy (parents and ancestors) for this owl:Class (see jOWL.UI.Tree as an example). Tree data is stored in the returned Array entries.

addInverse Add a variable invParents (jOWL.Ontology.Array of child references) to each parent node.

A jOWL.Ontology.Array jOWL.Ontology.Array containing topmost parents (classes directly subsumed by 'owl:Thing').

ancestors

A jOWL.Ontology.Array containing this class' ancestors.

sourceof

See the sourceof description on Individual.

A jOWL.Ontology.Array of owl:Restrictions satisfying the conditions.

myClass.sourceof(jOWL('someProperty'), jOWL('someTarget'))
	.each(function(){
	//do something
});

individuals

A jOWL.Ontology.Array containing all types/individuals of this class and it's subclasses. For more granularity, use SPARQL-DL type queries instead.

oneOf

A jOWL.Ontology.Array containing, if any, the Individuals in any oneOf collection declared on this class.

jOWL.Ontology.Individual

jOWL javascript equivalent to an owl:Thing.

Extends (inherits all properties and functions) jOWL.Ontology.Thing

Properties

isThing true.

Functions

owlClass

Get the jOWL.Ontology.Class for this individual.

sourceof

property Optional, A Property or a jOWL.Ontology.Array of Properties. Or null if no filtering should be applied. Returned Restrictions are filtered on the presence of the given properties.
target Optional, A Class, Individual, Literal/String or a jOWL.Ontology.Array of the previous. Or null if no filtering should be applied. Returned Restrictions are filtered on the presence of the given targets.
options Optional, Configuration Object.

A jOWL.Ontology.Array of owl:Restrictions satisfying the conditions.

var test = jOWL('Year1998').sourceof(jOWL("yearValue"));
alert(test.length == 1);

test = jOWL('Year1998').sourceof(jOWL("yearValue"), "1997");
alert(test.length == 1);

//with options
someThing.sourceof(null, someTarget, {inherited: false, transitive: false });

jOWL.Ontology.Property

jOWL equivalent to an rdf:Property. Extends (inherits all properties and functions) jOWL.Ontology.Thing.

Properties

isProperty true.
domain The domain of the property as a String (URI). May be null.
range The range of the property as a String (URI). May be null.

Examples

var domainObject = jOWL(myProperty.domain);

jOWL.Ontology.DatatypeProperty

jOWL equivalent to owl:DatatypeProperty. Extends (inherits all properties and functions) jOWL.Ontology.Property.

Properties

isDatatypeProperty true.

Functions

assert

Test whether data values (5, "astring", etc) match this properties range.

targetValue Value that will be checked, returns whether or not (true/false) the value falls witih the range of this property.
matchValue Optional, used internally for restriction querying to test an input value (targetValue) against the real restriction target (matchvalue). targetValue may be an expression in this case. If that is the case then the expression will be evaluated and the matchValue will be tested against it. (Example: assert("> 2 && <5", 3) == true if this is a datatypeproperty with range xsd:integer)

jOWL.Ontology.ObjectProperty

jOWL equivalent to an owl:ObjectProperty. Extends (inherits all properties and functions) jOWL.Ontology.Property.

Properties

isObjectProperty true.

jOWL.Ontology.Array

An array object, tailored for jOWL Ontology Objects. People familiar to jQuery might recognize some similar functionality.

Functions

bind

Map this array to some HTML elements for visual representation.

listitem Optional, specify a jQuery wrapped HTML object that will be cloned for each entry. Default a span element.
fn Optional, specify a function that will manipulate each created HTML element. The 'this' keyword and the first argument refer to the newly created jQuery wrapped HTML element. Second argument refers to the jOWL.Ontology.Array Item.

A javascript Array of DOM elements.

var elements = myArray.bind($('<li/>'), function(html, jowlObject){
	//manipulate html and or jowlObject.
});

//or for span nodes:

elements = myArray.bind();

$('somelistelement').html(elements);

concat

Merges a target array with this array.

arr An array (native javascript or jOWL.Ontology.Array). No duplicate elements are added in the case of a jOWL.Ontology.Array.

This array.

contains

Check whether this array contains the specified object.

object The object which will be checked for presence in this Array.

true/false

each

Looping Function, iterates throught the entire array.

fn The function that manipulates each entry of the array. Inside this function, the 'this' keyword and the first argument refer to the current Array element, the second argument to the array position. Explicitely return false to discontinue looping.
reverse Optional, if true then the array will be looped over in reverse order.

This array.

myArray.each(function(item, i){
	alert(this.URI);
	alert(item.URI);
	alert('The index is '+i);
});

myArray.each(function(){
	alert("The last element in the array is: "+this.URI);
	return false; //will stop looping immediately
}, true);

eq

filter

Looping Function, iterates throught the entire array and removes elements based on the input function.

fn The function that manipulates each entry of the array. Inside this function, the 'this' keyword and the first argument refer to the current Array element, the second argument to the array position. Explicitely return true to keep the element in the array.

This array.

myArray.filter(function(){
	return (this.URI == "keepMe");
});

get

Get a specific element from the Array.

map

Convert this array into a native javascript Array.

push

Add an element to this Array.

pushUnique

Add an element to this Array, but only if it is not already present.

jOWL.Ontology.Restriction

Equivalent to an owl:Restriction. Wraps property + target values (relations). Can be used within jOWL.Ontology.Arrays (contains, filter, etc).

Properties

isRestriction true/false.
isValueRestriction true/false.
isCardinalityRestriction true/false.
property jOWL Property for this restriction.
target Value for this restriction as a String (URI or Literal). Can be null if this is a cardinalityRestriction instead.

Functions

getTarget

The target as a jOWL Ontology Object.

jOWL.options

Object that can be specified as argument for load, parse and parseRDFa.

Properties

reason Enable all Reasoning, default true.
locale Set preferred language ('en', 'fr') for visualisation. Only useful in conjunction with 'rdfs:labels' containing 'xml:lang' attributes.
onParseError Function to be called when parsing fails. First argument is the parsing error message. Default: alerts.
niceClassLabels Default true, if no rdfs:labels are found for a given owl:Class, uses some regexp functions to format a more elegant label out of the identifier (add spaces etc).
dictionary.create Default true, creates a dictionary of terms used in this ontology, used for the autocomplete functionality.
dictionary.addID Default true, add identifiers of the ontology objects to the dictionary as well, under the language specified by 'defaultlocale'. If the identifiers are not relevant terms (e.g. of the form XX45458 or other numeric codes etc), then it might be more efficient to disable their inclusion.

User Interface Components

All user interface components can easily be re-styled, but some basic styling is provided by the jOWL.css file. All user interface components (widgets) share 3 important functions as specified below. To convert any object into a widget-like object (having the before mentioned functions) one can call: "jOWL.UI.asBroadcaster(theObject);".

Functions

propertyChange

item A jOWL Ontology Object, the widget will update itself with the given object.

myWidget.propertyChange(jOWLObject);

addListener

Make an other widget listen to this widget's selection events.

widgets Any object, or any javascript array of objects that possess a 'propertyChange' function (see above).

myWidget.addListener(anotherWidget);
myWidget.addListener([anotherWidget, yetAnotherWidget]));

broadcast

item A jOWL Ontology Object, this widget will trigger all propertyChange functions of the widgets that are added as listener (addListener) to this widget. E.g. it will update all dependent widgets.

myWidget.broadcast(jowlObject);
//-->updates anotherWidget, yetAnotherWidget;

Navigation Bar

Visualisation component that shows parents, children and the Class itself.

Extends jOWL User Interface Components. Function that can be called on any jQuery HTML element. Only accepts owl:Class entries.

Parameters

options Optional, Configuration object.

Example

var navbar = $('someelement').owl_navbar({
	focusClass: "my-focus", 
	onSelect : function(item){
		alert(item);
	}
});

Treeview - function(options)

Visualisation component that shows the hierarchy of a Class as a tree.

Extends jOWL User Interface Components. Function that can be called on any jQuery HTML element. Only accepts owl:Class entries.

Parameters

options Optional, Configuration object.

• rootThing: true/false - default false; if true then topnode is (owl) 'Thing'
• isStatic: true/false - default false; if static then selections will refresh the entire tree
• addChildren: true/false - default false; add a given objects children to the treeview as well
• onSelect: function that can be overwritten to specfy specific behavior when something is selected

Example

$('someelement').owl_treeview();

Autocomplete - function(options)

Uses jQuery syntax. Should be bound to an 'input' html element of the type 'text'. Example:

$('someinputelement').owl_autocomplete();

options

• time: responsetime to check for new keystrokes, default 500
• chars: number of characters needed before autocomplete starts searching, default 3
• focus: put cursor on the input field when loading, default false
• limit: limit size of result list to given amount, default 10
• html: allows specification of a custom function that will reformat the result list to the user's liking. Syntax:

  function(listitem, type, identifier, termarray){
  //listitem = jQuery element wrapped around the 
   element
  //type = type of the ontology object, example 'owl:Class'
  //identifier = identifier (name) of the ontology object
  //termarray = array of strings, containing the terms associated 
  with this ontology object that match the autocomplete query.
  }

Individuals Component - function(options)

Uses jQuery syntax. Only responds to owl:Class entries, shows matching owl:Thing's. Can be entirely replaced by an appropriate Property Lens, is maintained for ease of use only. Example:

$('someinputelement').owl_individuals();

options

• title: display the owl:Class name on top, default true
• tooltip: default false, display additional info in a tooltip, requires the tooltip script.
• html: if tooltip is enabled, the function that renders the html of the tooltip.

owl_propertyLens - function(options)

Uses jQuery syntax. Example:

$('someinputelement').owl_propertyLens(options);

Very flexible component, relies heavily on HTML templating, which means that most functionality can be tuned by altering the HTML inside the element converted into a propertyLens (hardly any javascript required). This documentation describes the additional javascript settings that can be added, but see the blog post for an extensive description of the HTML templating functionality.

options

• onChange: allows you to specify what should happen with elements referencing a given kind of ontology element (owl:Class, owl:Thing, ..) inside the lens. This allows for example to set up a tooltip that will be displayed each time an owl:Thing reference inside the lens is hovered over. See the jOWL generic Browser page for an example.
• onUpdate: a function that will be called each time the template has been updated with a new ontology element.
• passing data-jowl entries: see the jOWL generic Browser page for concrete examples.
  

  "rdfs:label" : {split: ",  ", "rdfs:label" : 
      function(){ //'this' keyword refers to HTML element}} )
  "sparql-dl:PropertyValue(owl:Class, ?p, ?x)" : {"?p": 
      function(){ //'this' keyword refers to HTML element }}

  
  
  • split: if multiple results are present, then this string will additionally be used to separate results (example: ', ').
  
  
  • "a parameter": a function that can be specified for any of the bracketed parameters (example: rdfs:comment) in the template. The function gives access to the specific HTML elements for this parameter.