Props (variables you can set in the tags)

Props Values
url url for range, annotation, manifest, collection link. If you want to display multiple annotations seperate the urls by a ; and the application will correctly build the view for you. Can also use datauri values for this variable (see Raw JSON page for details on using datauris.
annotationurl (deprecated, replaced with url) URl to the annotation. i.e. https://dnoneill.github.io/annotate/annotations/segins-004-001.json
annotationlist (deprecated, replaced with url) This has been moved to annotationurl. If you want to recreate the previous look of annotationurl that is now doable with the settings. ListAnnotation or PageAnnotation. See “@type” or “type” in annotation. i.e. https://dnoneill.github.io/annotate/annotations/segins-004-list.json
manifesturl iiif manifest url, only required when annotation does not contain manifest
styling string structured styling. See settings table for more options
ws link to web socket. Should have a wss:// or ws:/ preceding instead of https:// or http://. See web sockets section about how to set up
layers String in JSON format. Required fields are ‘label’ and ‘image’. Optional field of xywh. Read about what each of these are in the Add custom layers section.

Getting started

In order to create any of the viewers listed on the website the following code needs to be added to an HTML file once.

<script src="https://ncsu-libraries.github.io/annona/dist/annona.js"></script>

<link rel="stylesheet" type="text/css" href="https://ncsu-libraries.github.io/annona/dist/annona.css">

Note: the annona.js and annona.css need to be loaded only once, no matter how many storyboards are loaded. Multiple storyboards can be loaded on one page with the <iiif-storyboard> tag. An example of this can be seen here: annotation storyboards. Be aware that the last annotation in a list of annotations will be the color to display on top. The colors for the annotation tag types will be randomly generated. To override these colors see the CSS styling in the single annotation setting example.

Building views

From there any of the tags built through the Tag Builder or manually can be entered into a webpage. The Tag Builder provides a user interface for creating much of the code documented below. It also has all settings built into the interface.

Default AnnotationList or AnnotationPage Storyboard example

The code below makes use of default without any overrides or CSS styling. View example below in Tag Builder

<iiif-storyboard annotationurl="https://dnoneill.github.io/annotate/annotations/wh234bz9013-0001-list.json"></iiif-storyboard>

Icons & Keyboard Shortcuts

Icon Keyboard Shortcut(s) Purpose
b or 1 This button will automatically go through all the annotations and the sections associated with the annotation until stopped. When it is running it will be replaced with icon until it is pressed again.
j or shift+1 This button will reload the annotations in the viewer. If there are new annotations added, this will add those.
i or 2 This button will display a list of the annotations available. It also displays manifest metadata if a manifest is provided. Also it will show specialized information loaded through the settings. will appear when an annotation is clicked and will toggle back to the annotation. will appear when no annotation is clicked and will close the box.
t or 3 This button will display all of the tags in the storyboard and allow the users to view overlays based on tags. It works with resources with multiple tags, however they will display on top of each other so only one color is visible at one time. will appear when an annotation is clicked and will toggle back to the annotation. will appear when no annotation is clicked and will close the box.
o or 4 This button will display the sections that are annotated. When toggled on, these sections are clickable. It is replaced with when the toggle is active
l or 5 This button will show the layers available, allow for toggling them and changing the opacity on the layers. will appear when an annotation is clicked and will toggle back to the annotation. will appear when no annotation is clicked and will close the box.
z or + or shift+ (zoom in), m or - or shift+(zoom out) Zoom in/out buttons
h or 0 This button shows the full image, if an image is zoomed in, it will resize the image to the view on the original load.
p or , or shift+(previous), n or . or shift+ (next) These buttons allow users to scroll through annotations. They will be red when they have reached the end or beginning of the list.
alt+f(windows)/option+f(mac) or ; Will make viewer fullscreen, switches to when full screen.
x, 6 Will close the content box. Make sure to navigate to the viewer to use keyboard shortcuts.
( with collapse setting) c, 7 Will truncate the length of the annotation. Make sure to navigate to the viewer to use keyboard shortcuts.
v, 9 When text to speech(TTS) is enabled, this allows for playing/pausing the TTS.
s, 8 Will show keyboard shortcuts
g, alt+z Shows the text overlay view when there is transcription text in the annotations.
e, ` If there are transcription and annotations, switch between the two.
OpenSeadragon viewer https://openseadragon.github.io/examples/ui-keyboard-navigation/ The OpenSeadragon viewer also has keyboard navigation (the image section of the storyboard). See webpage for keyboard navigation like rotate and flip

Settings

This code is also customizable. Adding a configuration section to the code will provide options. The full page setting only works for one storyboard. An example can be seen here: all settings example. The example has set almost all options. They are interchangeable, any combination will work. They only need to be set if you would like to change the default settings. The code and options can be seen below. Like the image viewer these settings can be set for a single storyboard or all storyboards on a page.

Additionally each storyboard viewer has CSS that can be individually customized. The overlay color is set to lightblue on load and a lightgreen outline will appear inside the overlay when annotation is being viewed. This can easily be customized to each viewer. See Single annotation settings for an example.

Global Settings

Item here: global settings example

<script src="https://ncsu-libraries.github.io/annona/dist/annona.js"></script>
<link rel="stylesheet" type="text/css" href="https://ncsu-libraries.github.io/annona/dist/annona.css">

<script id="config" type="application/json">{
  "autorun_onload":true,
  "autorun_interval": 4,
  "hide_toolbar": true,
  "fullpage": true,
  "hide_annocontrols": true,
  "mapmarker": "<svg height='18' width='18'><circle cx='9' cy='9' r='5' stroke='black' stroke-width='3' fill='lightblue' /></svg>",
  "fit": "fill",
  "panorzoom":"pan",
  "toggleoverlay": true,
  "textposition": "right",
  "tts": "en",
  "hide_tags":true
}</script>
<iiif-storyboard annotationurl="https://dnoneill.github.io/annotate/annotations/4058a628-c593-463e-9736-8a821e178fee-list.json"></iiif-storyboard>

Single annotation setting

Annotation settings can be set inline. Additionally colors can be changed using CSS styling. The code below makes use of default without any overrides or CSS styling. View example below in Tag Builder

<div id="anno1" title="example info">
This is an example of the info that is loaded.
</div>
<iiif-storyboard annotationurl="https://ncsu-libraries.github.io/annona/webannotations/mc00084-001-te0159-000-001-0001-list.json" styling="fit: fill; panorzoom: pan; toggleoverlay: true; textposition: left; mapmarker: <svg width='20' height='20'><circle cx='10' cy='10' r='8' stroke='black' stroke-width='3' /></svg>; tts:it-IT; truncate_length: 5; additionalinfo: anno1; startenddisplay: info; title: Example custom title; tagscolor: {'standing': 'green', 'demolished': 'red'}; overlaycolor: orange; activecolor: yellow;"></iiif-storyboard>
This is an example of the info that is loaded.

AnnotationList or AnnotationPage Storyboard with Multiple languages

W3 standards allow for transitions between multiple bodies https://www.w3.org/TR/annotation-model/#choice-between-bodies. The assumption is only one body is used at a time. This library supports this model. The assumption this library makes is that the changes are between different languages which are defined in ISO standard in the annotation. An example of this can be seen in the storyboard below. View example below in Tag Builder

Manifests with layers

Some manifests define multiple images for a “canvas” allowing for images to be placed on top of each other. Three examples of annotations created on manifests with layers can be seen below. The layers can be toggled using the button.

<iiif-storyboard annotationurl="https://dnoneill.github.io/annotate/annotations/cdm17272contentdmoclcorg-14057-list.json"></iiif-storyboard>

View example below in Tag Builder

<iiif-storyboard annotationurl="https://dnoneill.github.io/annotate/annotations/4490-canvas-981394-list.json"></iiif-storyboard>

View example below in Tag Builder

Add custom layers

This allows for layers to be created without having to define the layers in a manifest. In order to add custom layers (no limit to number) a JSON object has to be set for the layers property. For ease of use I would suggest replacing fields in the example below. The label fields defines what will show up in the layer controller. This can be HTML as in the example below. The image field should be a IIIF image in info.json format. See https://iiif.io/api/image/2.1/#image-information-request-uri-syntax for more information on this format. The xywh field defines how the image gets layered on top of the top image. It should be four numbers separated with commas and no whitespace. In order they are x coordinate, y coordinate, width and height. Width is the measurement used to calculate the height, so figuring out the height is not necessary. In the example below the overlaid image is larger than the annotated image so xywh is set to 185,180,4750,6513. This means the image is moved down by 180 and to the right by 185 and the width of the image is set to 4750. rotation is the rotation of the overlaid image, the rotation is clockwise. section allows for a section of the image you have inputed.

Note: In order to determine the xywh and section fields try using any of the cropping tools listed on the Awesome IIIF list.

<iiif-storyboard annotationurl="https://dnoneill.github.io/annotate/annotations/131424-list.json" layers="[{'label':'<a href=\'https://www.wikidata.org/wiki/Q4792194\'>View from Arles</a>', 'xywh': '200,200,4750,6513', 'image':'https://tools.wmflabs.org/zoomviewer/proxy.php?iiif=Van_Gogh_-_Weizenfeld_mit_Blick_auf_Arles.jpeg/info.json'}]"></iiif-storyboard>

View example below in Tag Builder

<iiif-storyboard annotationurl="https://dnoneill.github.io/annotate/annotations/mc00084-001-te0159-000-001-0001-list.json" layers="[{'label':'Harrelson Hall', 'xywh': '4400,1300,3000,3000', 'image':'https://iiif.lib.ncsu.edu/iiif/0003310/info.json', 'section':'0,2952,2500,1696'}, {'label':'D.H. Hill Jr. Library', 'xywh': '3700,400,3000,3000', 'image':'https://iiif.lib.ncsu.edu/iiif/0003310/info.json', 'section':'0,384,6430,2500', 'rotation': 352}]" styling="togglelayers: true; customid: customlayers"></iiif-storyboard>

Transcription

No settings enabled

<iiif-storyboard annotationurl="https://ncsu-libraries.github.io/annona/webannotations/4665993.json"></iiif-storyboard>

Transcription setting only

<iiif-storyboard annotationurl="https://ncsu-libraries.github.io/annona/webannotations/4665993.json" styling="transcription: true;customid:transcriptionsetting"></iiif-storyboard>

Transcription with text first

<iiif-storyboard annotationurl="https://ncsu-libraries.github.io/annona/webannotations/4665993.json" styling="transcription: true;textfirst: true; customid:textfirstsetting"></iiif-storyboard>

Web sockets

Web sockets allow for communication across websites. In order to use this functionality a server will first need to be set up. An example of an easy server can be found here: https://github.com/dnoneill/sample-websocket. All this server is doing is receiving a broadcast from the controller and sending it back to all storyboards connected to the server. If you already have your own server the only listener you will need to know is below.

  socket.on('broadcast', (message) => {
    socket.broadcast.emit('message', message);
  });

In order to instantiate a controller the server url should be loaded into the storyboard. See the example below on how to instantiate the controller.

<iiif-storyboard ws="wss://websocketserver" annotationurl="https://dnoneill.github.io/annotate/annotations/wh234bz9013-0001-list.json" styling="controller: true;"></iiif-storyboard>

Another instance can be loaded in another webpage if a “receiver” is needed. This is not required. If you open the controller in multiple webpages they will mirror each other across devices. The reason for adding a receiver is to be able to customize the look and stop actions from being reflected back to all other pages.

<iiif-storyboard ws="wss://websocketserver" annotationurl="https://dnoneill.github.io/annotate/annotations/wh234bz9013-0001-list.json"></iiif-storyboard>

An example of the web sockets in use can be seen in the video below. The window on the far left has an instantiated item on a server and is a receiver (controller has not been set in settings). The two windows next to it are the same URL and are the controllers. As you should be able to see from the video, the receiver can still navigate through the annotations but it will not affect the controllers. Additionally, on reload of the receiver the toolbar disappears. Like all aspects of the library elements can be hidden with the CSS functionality.

The instantiated storyboards do not have to be the same object, however they should be the same number of annotations. The video below shows two different annotations list on the same page of the The Cantebury Tales but in different versions. This can also now be done without websockets see Multi Storyboard for more info

Auto Language TTS example

This annotation has the language set for each of the annotations in the annotation list. This allows for the language to be set for TTS using the annotation data instead defining the language in the settings.

<iiif-storyboard annotationurl="https://dzkimgs.l.u-tokyo.ac.jp/iiif/zuzoubu/12b02/list/p0001-0025.json" manifesturl="https://dzkimgs.l.u-tokyo.ac.jp/iiif/zuzoubu/12b02/manifest.json" styling="tts:true"></iiif-storyboard>

Single Annotation Storyboard

This functionality has been depracated but can be recreated by the use the settings below

<iiif-storyboard annotationurl="https://dnoneill.github.io/annotate/annotations/qva4uqb6ncml7jyjq0er.json" styling="startposition: 1; toggleoverlay: true; hide_nextbuttons:true;"></iiif-storyboard>