The Research Computing Group, in support of RERUM annotations, offers this simple project for quickly creating exhibitions of annotated collections.

Installing DEER

To install the script on your project, use the deer.js on your page.

<script src="//deer.rerum.io/DEER/releases/alpha-0.11/deer.js" type="module"></script>

View the wiki or read on for details.

Templates

Use the <deer-view> element or .deer-view class to automatically connect the DEER renderer to your page. 

<deer-view deer-id="https://example.com/id/001"></deer-view>

The DEER module will automatically detect these elements and watch the deer-id attribute, rendering the resolved object inside. There are several templates available to you or you can create your own.

JSON template (default)

DEER will construct an object combining the resolved deer-id value with the results of a query for annotations targeting it. The JSON template simply displays the result.

JSON Template
<deer-view 
    deer-template="json"
    deer-id="https://example.com/id/001">
</deer-view>

Entity template

The entity template attempts to render the object properties as a definition list, as is typically displayed as metadata or Dublin Core terms.

Entity Template
<deer-view 
    deer-template="entity"
    deer-id="https://example.com/id/001">
</deer-view>

Person template

The person template attempts to render the object properties as a person's profile.

Person Template
<deer-view 
    deer-template="person"
    deer-id="https://example.com/id/001">
</deer-view>

List template

The list template shows items connected in an aggregation. The same template can be used for static and dynamic lists as explained in the wiki.

List Template
<deer-view 
    deer-template="list"
    deer-list="itemListElement"
    deer-id="https://example.com/id/001">
</deer-view>

Property template

A simple template for showing a single property.

Property Template
<deer-view 
    title="Sample Prop" 
    deer-key="name"
    deer-template="prop"
    deer-id="https://example.com/id/001">
</deer-view>

Customization

Though the default options may be limited, it is simple for a developer to extend existing templates or create a new one from scratch. The complete instructions can be found in the wiki.

Custom template

A simple template made to show a cat.

Cat Template
<deer-view 
    deer-template="cat"
    deer-id="https://example.com/id/001">
</deer-view>
TEMPLATES.cat = (obj) => `<h5>${obj.name}</h5>
    <img src="http://placekitten.com/300/150" style="width:100%;">`

Configuration

The deer-config.js file contains all the defaults for using DEER. Any developer wishing to rename watched attributes, to attach new templates, and more can extend this configuration object when initializing DEER.

Interactions

Developers can extend regular application logic to update and connect their interfaces by using the DEER Event system or rely on a few simple interactions for the bulk of users needs.

Using deer-link

In any <deer-view> element, the deer-link attribute instructs the templates how to attach links to the rendered object. For lists, each item with an @id property will include an anchor tag hyperlinking to the deer-link URL joined with the @id. This example simply changes the hash on the current page. Be aware of this default behavior if you are using a SPA framework that relies on hashes for routing and consider "Listening to Events" instead.

List Template with Links
<deer-view 
    deer-template="list"
    deer-list="itemListElement"
    deer-link="#"
    deer-id="https://example.com/id/001">
</deer-view>

Listening to the Hash

Building on the example above, it is possible to load new objects into elements by watching the hash and updating the deer-id attribute. The DEER observer will rerender the contents immediately. 

window.onhashchange = () => hashExample.setAttribute("deer-id", window.location.hash.substr(1))
List Template with Links
Click on a link in the list to update the rendered element on the right.
Load from Hash
no hash

Listening to Events

Another option that is more transparent to the user and allows for more flexibility is to use the deer-listening attribute to tell one <deer-view> element to watch another for clicks and load the render the resulting object.

List Template with Links
Click on a list item to update the "listening" <deer-view> elements below 
<deer-view 
    id="exampleListen"
    deer-template="list"
    deer-list="itemListElement"
    deer-id="https://example.com/id/001">
</deer-view>

<deer-view 
    deer-template="person"
    deer-listening="exampleListen">
</deer-view>
Listening with a Person Template
Listening with an Entity Template

Forms

Adding new entities and annotations is a simple process (wiki). Update your <form> with deer-type and deer-key attributes. 

<form deer-type="Thing" deer-context="http://schema.org" deer-id="https://example.com/id/001">
    <label>Label:</label>
    <input type="text" deer-key="name">
    <input type="hidden" deer-key="creator" value="demoAgent">
    <input type="date" deer-key="date">
    <select>
        <option>Example choice</option>
        <option>Unknown to DEER</option>
        <option>Use as usual</option>
    </select>
    <textarea deer-key="description"></textarea>
    <input type="submit">
</form>
Thing Form -- You may change the date.

This form preloads with recent annotations on this entity. The card to the right updates with every change as well, even if someone else has made the changes.

The <select> has no deer-key attribute, so no annotation is made. This can be used for local application logic before saving.
Listening to the Form

There are many more complex ways forms acquire data through UI to accommodate more complex data objects that you may want to record. How to process data from customized UIs is not well-documented yet, but we have many examples in our public code that we can direct you to upon request.

Simple Forms

Sometimes all you need is a simple form. If you add the attribute deer-item-type="simple" to your form, instead of designating each field into an annotation, DEER will save it to a simple object with properties. This should be reserved for objects that do not require a history of modification or attribution as when you do this within the DEER framework, several compromises must be made:

  1. Automatic Overwrite. The overwrite flag is added to each update, so the object URI persists. This also means that changes are not retained with each update and the __rerum property only shows the most recent modification.
  2. Restricted Updates. Only the generator of the original object can implement an overwrite, using the same API key for the RERUM store. If a change is still required, the application can fork the original object (save a new version) and overwrite that one. DEER does not do this automatically.
  3. Ambiguous Interoperability. Because another application may treat the original object as an entity and annotate it, the combined result may not be what is expected. The expand() function of DEER builds an object by appending annotations onto the base entity. This makes it difficult to explicitly remove properties or keep up with ongoing overwrites in the original object. The application can filter this, by checking the modification date on the original, but the history is unavailable. 

<form deer-type="Thing" deer-item-type="simple" deer-context="http://schema.org">
    <label>Label:</label>
    <input type="text" deer-key="name">
    <input type="hidden" deer-key="creator" value="demoAgent">
    <input type="date" deer-key="date">
    <select>
        <option>Example choice</option>
        <option>Unknown to DEER</option>
        <option>Use as usual</option>
    </select>
    <textarea deer-key="description"></textarea>
    <input type="submit">
</form>
Simple Thing Form -- You may change the date.

This form preloads with the most recent object. The card to the right updates with every change as well.

The <select> has no deer-key attribute, so no annotation is made. This can be used for local application logic before saving.
Updating Simple Objects
The first property is on the base object, so it remains, even though the form does not edit or update the value.