The only thing required is a SPARQL server. Before starting to use Hercules, you need to prepare your SPARQL server that holds RDF resources. If you don't have it yet, build it up in advance.
To import the Hercules library file to your web application, add a script element to your html file with putting "http://www.arielworks.net/works/codeyard/hercules/hercules.js" into its src attribute.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja">
<head>
<title>Hercules Tutorial</title>
<script type="text/javascript" charset="UTF-8" src="http://www.arielworks.net/works/codeyard/hercules/hercules.js"></script>
<script type="text/javascript" charset="UTF-8" src="./tutorial.js"></script>
</head>
<body>
<p>Let's create a web application with Hercules!</p>
</body>
</html>In this tutorial, the script of the web application will be written in "tutorial.js" at the same directory. So I added one more script element to the head element.
First of all, you must create an instance of the Hercules class. This class is the core of Hercules, and almost all processes are excuted by the instance of this class.
The constructor of the Hercules class takes the URI of your SPARQL server.
var e = new Hercules("http://uri/of/sparql/server");
e.registerPrefix("", "http://purl.org/dc/elements/1.1/");
e.registerPrefix("foaf", "http://xmlns.com/foaf/0.1/");Then, register the prefixes of namespaces you often use by the registerPrefix() method. This method takes a prefix name at the first parameter and its namespace URI at the second parameter. If an empty string is given, the namespace will be considered as the default namespace.
Here are sample triples pooled at your SPARQL server. Very simple statements about Alice.
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix dc: <http://purl.org/dc/elements/1.1/> .
<urn:for:alice> foaf:name "Alice" .
<urn:for:alice> foaf:nick "Rabbit" .
<urn:for:alice> foaf:nick "Queen" .
<urn:for:alice> foaf:homepage <http://example.com/alice/> .
<http://example.com/alice/> dc:title "Alice in Wonderland"When you know the URI of the resource which you want to fetch from the server, you can use the find("<URI>") method.
var alice = e.find("<urn:for:alice>");Note that the URI of Alice is delimited by the "<>". When the given string is not delimited, the method considers it as a QName (e.g. dc:title). After registration of the namespace prefix, you can shoten full URI with QName.
e.registerPrefix("for", "urn:for:");
var alice = e.find("for:alice");You can use the getValue() method to get the URI of a resource. And the $() method is defined as a shortcut to this.
alice.getValue(); // -> "urn:for:alice"
alice.$() // -> "urn:for:alice"To access to the predicates and the objects of Alice, you can use getAllObjects("<URI of predicate>"), getObject("<URI of predicate>") and getAllPredicates().
The getAllObjects("<URI of predicate>") method takes the URI of a predicate and returns all objects associated with the predicate as an Array. The getObject("<URI of predicate>") is a shortcut to getAllObjects("<URI of predicate>")[0] and returns only one object everytime.
(By the way, when use the getValue() method to "Literal" resources, the method returns the contents of them.)
alice.getAllObjects("foaf:nick")[0].$() //-> "Rabbit"
alice.getAllObjects("foaf:nick")[1].$() // -> "Queen"
alice.getObject("foaf:name").$(); // -> "Alice"
// You can connect predicates by dot notaion.
alice.getObject("foaf:homepage").getObject("title").$(); // -> "Alice in Wonderland"The getAllPredicates() method returns all predicates of a receiver resource as an array.
alice.getAllPredicates()[0] // -> "http://xmlns.com/foaf/0.1/name"You can shoten your code with shortcut methods defined as "prefix$localpart()". These shurtcut methods will be automatically defined when the prefix of the uri of the predicate is registered.
alice.foaf:name().$(); // -> "Alice"
alice.foaf$homepage().title().$(); // -> "Alice in Wonderland"
// When want to get all objects, add an "ALL" to the first parameter.
alice.foaf$nick(ALL)[0].$() //-> "Rabbit"When you want fetch resources by their class, You can use RDF-Class-based search.
The defineExistClasses() method of the Hercules class defines automatically JavaScript classes correlating to RDF Classes. This means the Hercules queries about subclasses of "http://www.w3.org/2000/01/rdf-schema#Class" to the server and defines JavaScript classes according to the result.
The defined classes have the findAll() method. This method returns all instance resources of the class.
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
<urn:for:alice> foaf:name "Alice" .
<urn:for:alice> rdf:type foaf:Person
<urn:for:bob> foaf:nick "Bob"
<urn:for:bob> rdf:type foaf:PersonYou can write the following code against these triples.
// define JavaScript classes.
e.defineExistClasses();
// Classes are defined as a property of the instance of the Hercules class
var people = e.foaf$Person.findAll();
people[0].foaf$name().$(); // -> "Alice'
people[1].foaf$name().$(); // -> "Bob'