Callimachus allows you to save a SPARQL query so that you can execute it every time to resolve its URL.  We call this a "named query".

Named queries have two features that make them quite useful:  They can accept parameters and their results can be rendered to HTML pages using Callimachus view templates.  The full documentation is available.

Writing a Named Query

The tutorial comes with two versions of a named query that returns all instances of the class Person.  Look in the folder /initial-app/queries to see the query.  Look first at the query called simple-person-listing.rq.  The query definition is:


#
# @Cache-Control: 
# @infer true
# @view
#
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?person WHERE {
    ?person a <../classes/Person>
} ORDER BY ?person

You are presented with a page that shows the results of the query whenever you look at a named query in a browser.  Callimachus provides that functionality by default using a Callimachus view template.  Callimachus is mostly built using Callimachus. 

If you want the raw SPARQL results (e.g. to use from JavaScript or some other code external to Callimachus), you can resolve the query's URL with the query string "?results" (instead of "?view").  You can try that for the simple-person-listing.rq query by selecting this link.  The results of the query should be downloaded by your browser.  They are in SPARQL's XML results format.

Selecting an RDF Query from a Folder's Create menuYou can create your own named queries by selecting the menu option "RDF query" from the Create menu on any Callimachus folder.  Note that the .rq file extension is commonly used for SPARQL queries.  You should use that extension when creating your own queries.

Displaying Named Query Results using a View Template

You can also customize the display of named query results by assigning a view template to the query.  Query results are then rendered by your view template instead of the default template.  Two steps are necessary to do this:

  1. Create a view template to render the results of your query
  2. Add a comment (technically, a pragma) to your named query listing the template URL

That's it!  It is very easy to use view templates with named queries.

The initial app folder contains a simple view template to render the results of the Person listing query.  Look in the initial app/templates folder for the template person-list-view.xhtml.  That 

  1. Create simple address book listing page
  2. Use the variable returned in your named query to set the scope
  3. Write this template the same way you would the view template for a Callimachus class

Associating a Named Query with a View Template

  1. Click the Edit tab of the Named Query you created earlier.
  2. Change the @view pragma at the top of the query to point to the location of the view template you just created. 
  3. When you click Save you will be redirected to the View template of the Named Query. Notice now, however, the View template of the Named Query renders the results in the context of the file specified in the @view pragma (../templates/person-listing-view.xhmtl), rather than the default table layout.

# @Cache-Control: 
# @infer true
# @view ../templates/person-listing-view.xhtml
#
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?person WHERE {
    ?person a <../classes/Person>
} ORDER BY ?person
Default Query View Named Query with View Template

Wrap Up & Review

Named Query view templates are very similar to view templates for Callimachus classes. The main difference is that instead of using the implict ?this to set the context for the template, you use ?{variable-returned} to connect the template to the query. From this point you can operate using the same syntax and structure, expanding as necessary. These can also be used with parameters as any normal named query would be.