Danno User Guide
This page describes the Danno user interface, as exemplified by the demo pages in the vanilla Danno WAR file. A "real" deployment of Danno is likely to re-skin, restrict, hide from view or even entirely remove some or all of these pages.
The Danno query page is primarily a demonstration of Danno's query functionality. As explained on the page, the query page models that a query has three parts:
- a primary query that selects a base result set of objects from the Danno triple store,
- an optional set of restrictions that filter out objects in the base result set, and
- a specification of how the restricted result set is displayed.
The primary query is controlled by the radio buttons at the top of the query form. The four query types supported at this level are as follows:
- "Query Annotations for URL" selects all Annotations associated with a specified URL (e.g. web page), using the Annotea "w3c_annotates" query. The URL of an annotated resource must be supplied.
- "Query Replies for Annotation" selects all Replies associated with a specified Annotation, using the Annotea "w3c_replyTree" query. The supplied URL should be the URL of an Annotation stored on this server.
- "Query all Objects" selects all objects using the "danno_allObjects" query. No URL is required.
- "Query all Annotea Objects" selects all Annotation and Reply objects using the "danno_allAnnoteaObjects" query. No URL is required.
The restrictions on a query are specified in the next table rows. Each consists of a checkbox that controls whether the restriction is applied, and a form field for a restriction value. If you select multiple restrictions, they are AND'ed together.
The restrictions currently supported by the query form are as follows:
- "Restrict by Creator" restricts to objects with a specified value for the DC "creator" property.
- "Restrict by Language" restricts to objects with a specified value for the DC "language" property.
- "Restrict by Collection Id" restrict to objects with a specified URL for the Danno "collection" property. Refer to the Danno Import section for details on collection ids.
- "Restrict by Source" restricts to objects with a specified URL for the Danno "source" property; Refer to the Danno Import section for details on this property.
- "Restrict by Annotated URL regex" restricts to objects whose "annotates" property contains a string that matches the supplied regular expression. This can be used (for example) with "Query all Annotea Objects" to select all Annotations for an entire website rather than a single page.
- "Restrict by Date Range" restricts to objects with a date property whose value is in a given range. You can choose between restricting on the object's creation date, the (last) modification date or the date (if any) that it was imported into the triple store. Alternatively, you can select on the 'dc:date' property which is used for OAI harvesting. A date range is specified as lower bound, an upper bound or both. Dates should be entered as ISO date-time stamps.
The buttons near the bottom of the form submit the query to the Danno server or reset the form fields, buttons and checkboxes. The radio buttons beneath determine how the result set is presented.
- "Format as web page" formats the results as a web page using a standard style-sheet.
- "Format as RDF" sends the results to the browser as raw RDF/XML and will be displayed in a browser-specific way.
- "Format as RSS feed" sends the results to the browser as an RSS feed format, and displayed / handled in a browser-specific way.
Once again, please note that the demo query page is not indicative of what a query interface for end-users should look like. It's purpose is to allow you to try out Danno's query engine without having to construct and enter Danno query URLs by hand.
The Danno Import page demonstrates a simple annotation file import facility for Danno. The primary use-case assumes that the you have created a collection of annotations in some other annotation tool or system, and now want to share them with other people via Danno / Dannotate.
First, the you export the annotations from the annotation tool to a file on (say) the the hard drive of your computer. Then you visits the Danno Import page (or equivalent) and use the form to import the annotations. This uploads file to the Danno server, extracts the annotations in Annotea compatible form and adds them to the Danno triple store.
All annotations added to the triple store by the import facility are tagged with a "Collection Id". This allows them to be subsequently updated or deleted as a group. You can manage your own collection ids (they need to be valid, unique URLs) or let Danno create them for you. The collection id that is assigned to your collection will be shown in the output page. To make things easier, the import facility allows you to refer to your collections by name, avoiding the need to take a note of the collection ids used.
You can also choose to ignore the collection concept entirely, but this will make it hard to update or delete the imported annotations.
Imported annotations are also tagged with these properties:
- A "Source" property says where the annotation was imported from. This is currently either "pliny" or "danno", but it could be revised to be a URL that identifies the source repository.
- An "Imported" property gives the date/time that the annotation was imported.
- An "Original Id" property is used to give the source identifier for the annotation. This property is used to match annotations when you update a previously imported collection.
The following steps should be used to import a collection of annotations using the form on the Danno Import page.
- Use the Browse button to select the file on your local machine that contains the annotations to be imported.
- Use the "File format" pulldown to select the import file type. The current options are "Danno annotations" as produced by the Aus-e-lit tools, and "Pliny annotations" as produced by the Pliny personal annotation tool.
- Enter an optional "Collection Name" or "Collection Id".
- Enter a Creator name in the case where the annotation file does not include creator names.
- Click "Import annotations" to upload the collection.
If all is well, the annotations will be added to the triplestore. You should see a page that tells you how many annotations were added, and what collection id was used for the collection.
The following steps should be used to update a previously imported collection of annotations.
- Use the Browse button to select the file on your local machine that contains the new version of the annotations.
- Use the "File format" pulldown to select the import file type as above.
- Enter an "Collection Name" or "Collection Id". In this case, you must supply one of these, otherwise the importer has no way of knowing which of the existing annotations are to be updated.
- Enter a Creator name in the case where the annotation file does not include creator names.
- Click "Update annotations" to update the collection.
If all is well, the annotations will be updated. You should see a page that tells you how many new annotations were added, and how many existing ones were updated or deleted.
The following steps should be used to update a previously imported collection of annotations.
- Enter the "Collection Name" or "Collection Id" for the collection to be deleted.
- Click "Delete annotations" to delete the collection.
If all is well, all annotations in the collection will be deleted together with any replies that were subsequently created by Danno.
Danno's OAI-PMH pages are simply a copy of the OAICat test pages that have been tweaked to use the local Danno OAI-PMH APIs. There is a one-to-one mapping between these pages and the methods provided by the OAI-PMH protocol, so if you want to try out this interface, you should start by reading the Open Archives Initiative documents for OAI-PMH version 2.
Note that OAI-PMH is designed for harvesting metadata rather than for user-facing queries.
The Danno / Dannotate Admin tool is a web-based tool for doing simple administration tasks. The latest version of the tool has two tabs:
- The Record Manager tab has functions for editing and deleting annotations and replies outside of the context of the page that they annotate.
- The Store Manager tab has functions for dumping and loading the triplestore, and resetting the store contents.
