Classes, Instances and What They are Good For

A "class" is "a set or category of things having some property or attribute in common and differentiated from others by kind, type, or quality".  So, a class of cars includes my car and your car.  A class of people includes you and me.  A class of software includes Callimachus, Microsoft Sharepoint, Oracle's database and the game Angry Birds.

Callimachus allows you to define classes of information objects using the Web Ontology Language (OWL).  OWL classes may be defined in RDF data or you can make them yourself using the Callimachus user interface.  See the documentation for creating a new class if you want to make your own.

Let's start by exploring the classes and templates for the finished address book application.  Later, we will walk through the creation of them from scratch.

This tutorial already supplies a class that describes a person (see the Person class in the tutorial's initial app/classes folder or the Person class in the finished app/classes folder) so you don't need to create your own class right now.  We will explore what that class is, how to make instances of it (that represent real people) and how to use it to generate HTML pages to create, edit and view them.

Start by navigating to the finished app's Person class and selecting "Create a new Person" from the main menu.  Note that the "Create a new Person" menu item only appears when you are looking at the Person class.  The main menu is contextual and shows you relevant information depending on what you are currently doing.

Create a new Person

How does Callimachus know how to create an instance of a Person class?  The secret is that each class has up to three templates associated with it:

  • Create templates create a new instance of an OWL class
  • Edit templates are used to edit instances of an OWL class
  • View templates are used to view instances of an OWL class (or other things, like a SPARQL named query or XProc pipeline - more on that later)

The "Create a new Person" menu item tells Callimachus to serve the create template for the Person class.  The create template is just an HTML form that, when submitted, tells Callimachus to create a new instance of that class.  Since a create template is just XHTML, you can make it look like anything you want, can use CSS and JavaScript and can cause it to create instances of very complex classes.  RDFa markup is used to provide the hints that Callimachus needs to create compliant RDF data when you submit the form.

A new person

Fill out the create template with some information about yourself or another person.  It would be good if you included a profile picture (see the lower right of the screen) because it will look impressive later :)  Select the "Create" button when you are finished.

You will be asked to save the data for the new person via a dialog box.  Navigate to the folder Tutorial/finished-app/people/ and select the "Save" button as shown below.  You should try to save all your instances in a folder to keep your information organized, but should also know that Callimachus doesn't care where your data is stored.  Your people folder will probably only contain one example entry for "Joe Bloggs" the first time you use it unless you are sharing your Callimachus instance with others.

Save a person

Callimachus will save your new Person instance and redirect you to the view template for a Person, which is filled in with that person's information.  Whew!  In other words, Callimachus uses the view template for the Person class to make a Web page for each instance of the class. These pages are created dynamically when they are requested, so you won't be able to find them anywhere in the file system. The view for a Person instance is shown below.

A person view

You can change the view template to control exactly how you want a Person instance to look, just like you can change the create and edit templates to collect the data you want.  We generally make the create and edit templates look very similar to each other.

Let's look at the data that was created.  Select the "Describe" tab to the upper right.  You will see a stylized presentation of the RDF data that you just made about Joe Bloggs:

Person describe

You can use the hyperlinks in the upper right to download the raw data about your new Person instance if you like.

Instances of a class may be seen via the class view page.  You can use Callimachus to create your own custom views of any data you have!  The default instance list is accessible from the "Person resources" menu item in the main menu when you are on the Person class page:

Person resources menu item

Person instances

Review of the tutorial steps for this section:

  1. Go to the finished app's Person class
  2. Create an instance of the Person class
  3. View the instance of the Person class
  4. Review the data in the Describe tab
  5. Find any other instances of the Person class

How Templates Work: The Create Template

Now let's look at how the templates actually work.  We will explore the simplest possible create, view and edit templates used for the Person class in the initial app folder.

Start by opening the Person class in the initial app folder and looking at the templates associated with that class.

Edit the create template for the Person class in initial app folder to see its contents.

The create template is located in the initial app/templates/ folder.  You can edit the create template by selecting the file and then its Edit tab (or by selecting this link to the same URL).

The create template's <form> tag needs to create a Person resource on the Callimachus server.  The tag definition is a bit complicated and uses some built-in JavaScript functions.  You will not need to understand this right now because it is always the same or very similar.  For now, you can always include the same syntax when you make create templates.  Look for the <form> tag (line 15 in the template):


<form role="form" method="POST" action="" enctype="application/rdf+xml" typeof="" onsubmit="return calli.saveResourceAs(event,calli.slugify($('#label').val()))">

Edit the create template and look for the following lines (lines 18-21 in the template):


<div class="form-group">
     <label for="label">Name (Required)</label>
     <input type="text" class="form-control" id="label" value="{rdfs:label}" required="required" autofocus="autofocus" />
</div>

These lines provide the label and text input box for the new Person's name.  The <label> element provides the label (just marked as "Label" in the default create template) and the following <input> element provides the text field.  Note that the value for the <input> element is set to the term {rdfs:label}.  This means that the value that you type in the text field will be associated with the URI of the newly created Person in an RDF triple, like this:


<joe+bloggs> rdfs:label "Joe Bloggs"

All of the fields in the create template work in a similar way.  You can make any statement about the resource you are creating by providing the appropriate HTML form element and assigning its value to the RDF predicate that you wish to use for that statement.

Naturally, some parts of templates are a bit harder such as select widgets (pull downs), uploading images, etc.  Those will be covered later.  If you can't wait, please see the template language documentation.

The last thing you should notice in the create template is that the form needs to be submitted to Callimachus, so the form must include a Create button.  You could call it "Save" or any other name if you like.  See line 27 in the template.


<button type="submit" class="btn btn-success">Create</button>

Review of the tutorial steps for this section:

  1. Find the create template for the Person class
  2. Understand the create template's HTML and RDFa markup
  3. Map the markup to the generated page

How Templates Work: The View Template

A view template defines how an instance of a class is to be shown to the public.  It is the primary way that end users will see Callimachus resources.  A view template presents specific data as a friendly HTML page.

The view template for the Person class is, like all Callimachus templates, just an XHTML page with some RDFa markup.  The means that it can be styled and given interaction using CSS and JavaScript as you see fit.  The default view template doesn't use any CSS or JavaScript but is styled using the site-wide Callimachus layout file.  We will add more functionality and styling to the view template later.

A view template is easier to write than a create because it is just an HTML page, not an HTML form.  The magic in a view template is the resource attribute on the <body> tag:


<body resource="?this">

That attribute tells Callimachus to replace ?this with the URI of the resource that was requested.  So, if you ask Callimachus for the URI for the Person instance called <joe+bloggs>, ?this becomes the fully qualified URI for Joe.  That might be something like http://localhost:8080/Tutorial/initial-app/people/joe+bloggs (but your path might vary).  All the other information on the view template will be found by locating that URI in Callimachus' RDF database and "walking the graph" from there.  A create template doesn't use this attribute because it isn't created until the create template is submitted.

All of the information in the Person view template is written in the HTML in a manner similar to the create template's syntax, but without the form elements.  For example, the Person's name is shown with (line 16 in the template):


<h1 property="rdfs:label" />

This could also be written as:


<h1>{rdfs:label}</h1>

The two syntax forms yield the same result.  The curly-bracket notation is not legal RDFa but is provided as a handy shortcut form.  It is particularly useful when you want an HTML element to contain information from more than one RDF property and/or to mix RDF and defined text, like this:


<h1>Person's name: {rdfs:label}</h1>

If you understand the RDF data that was created for a Person, it is easy to write a view template!  If you don't know the data well, the Describe tab can show it to you.

Review of the tutorial steps for this section:

  1. Edit the Person class
  2. Understand the view template's HTML and RDFa markup

How Templates Work: The Edit Template

The Edit tab on any resource in Callimachus allows you to edit that resource.  There is only one trick:  You need to have defined an edit template for that resource type.

Fortunately, an edit template is a lot like a create template.  They are nearly identical except for three small differences.  They are so small that we generally cut-paste-and-modify a create template to make an edit template.

1.  An edit template needs to refer to a resource that already has a URI.  So, you will need to add a resource attribute to the <body> tag, like you did for a view template:


<body resource="?this">

2.  Next, an edit template's form generates a SPARQL UPDATE request to the server instead of a TODO.  So, the <form> tag needs to look like this:


<form role="form" method="POST" action="" enctype="application/sparql-update" resource="?this">

3.  Finally, an edit template may be used to delete a resource.  The edit operation can also be canceled (which has no effect other than to redirect the user back to the view template).  These features are provided by adding some additional buttons to the bottom of the edit template.  The buttons called built-in JavaScript functions:


<div class="row">
    <div class="col-sm-12 form-group">
        <button type="submit" class="btn btn-primary">Save</button>
        <button type="button" onclick="window.location.replace('?view')" class="btn btn-default">Cancel</button>
        <button type="button" onclick="calli.deleteResource(event)" class="btn btn-danger">Delete</button>
    </div>
</div>

You have complete creative control over the contents of an edit template.  You can protect some fields from being edited by simply not exposing them on the form!

Try going to an instance of the Person class and editing its values.  You are changing values in the RDF database by submitting an HTML form. This ability to round-trip RDF data is one of Callimachus' most useful features.  It is made more powerful by allowing developers complete control over which fields get updated and how the pages appear. 

Review of the tutorial steps for this section:

  1. Create an edit template for the Person class
  2. Understand the edit template's HTML and RDFa markup, including how it differs from a create template
  3. Choose which fields to expose for editing
  4. Test by editing an instance of the Person class

Wrap-Up & Review

There are 3 kinds of templates - Create, View and Edit. They're all associated with a Callimachus class and define how class instances are created, viewed and edited.