Home

Awesome

ipfs-iiif-db

IIIF annotations JS client over IPFS

CLI

You can run a node from the command line, and it will keep track of all the recors inside a partition.

$ ipfs-iiif-db-track [partition]

partition defaults to "iiif".

The tracker will save all the changes into a local leveldb database.

JavaScript API

Install

$ npm install ipfs-iiif-db --save

Import

In thr browser environment, you can either use this library by including it and bundling your app together with it (using browserify or webpack, for instance), or you can

in Node.js or in a browser with a bundler:

const DB = require('ipfs-iiif-db')

Using a script tag in a browser

<!-- loading the minified version -->
<script src="https://unpkg.com/ipfs-iiif-db/dist/browser.min.js"></script>

<!-- loading the human-readable (not minified) version -->
<script src="https://unpkg.com/ipfs-iiif-db/dist/browser.js"></script>

Now you can access this library using the IpfsIiifDb on the global namespace. (In this case, replace DB on the examples below with IpfsIiifDb).

Instantiate

const db = DB([options])

Arguments:

Annotation list

Get an annotations object:

const annotationList = db.annotationList([originalAnnotationList])

Arguments:

If a string is given as first argument, it's assumed as the '@id' attriubute of the annotation list.

annotationList API:

annotationList.set (key, value)

Set a annotation list attribute key to a given value

annotationList.set('@context', 'http://iiif.io/api/search/0/context.json')

annotationList.pushResource (resource)

Insert a resource at the end of the resources array.

annotationList.pushResource({
  "@id": "https://wellcomelibrary.org/iiif/b18035723/annos/searchResults/a2h0r885,2553,282,46",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource": {
    "@type": "cnt:ContentAsText",
    "chars": "gediegenen"
  },
  "on": "https://wellcomelibrary.org/iiif/b18035723/canvas/c2#xywh=885,2553,282,46"
})

putResource (index, resource)

Insert a resource at the given position inside the resources array.

annotationList.putResource(3, {
  "@id": "https://wellcomelibrary.org/iiif/b18035723/annos/searchResults/a2h0r885,2553,282,46",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource": {
    "@type": "cnt:ContentAsText",
    "chars": "gediegenen"
  },
  "on": "https://wellcomelibrary.org/iiif/b18035723/canvas/c2#xywh=885,2553,282,46"
})

deleteResourceAt (index)

Delete the resource at the given index position.

annotationList.deleteResourceAt(3)

getResources ()

Return the resources array.

annotationList.getResources()

pushHit (hit)

Insert a hit at the end of the hits array.

annotationList.pushHit({
  "@id": "https://wellcomelibrary.org/iiif/b18035723/annos/searchResults/a2h0r885,2553,282,46",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource": {
    "@type": "cnt:ContentAsText",
    "chars": "gediegenen"
  },
  "on": "https://wellcomelibrary.org/iiif/b18035723/canvas/c2#xywh=885,2553,282,46"
})

putHit (index, hit)

Insert a hit at the given position inside the hits array.

annotationList.putHit(3, {
  "@id": "https://wellcomelibrary.org/iiif/b18035723/annos/searchResults/a2h0r885,2553,282,46",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource": {
    "@type": "cnt:ContentAsText",
    "chars": "gediegenen"
  },
  "on": "https://wellcomelibrary.org/iiif/b18035723/canvas/c2#xywh=885,2553,282,46"
})

deleteHitAt (index)

Delete the hit at the given index position.

annotationList.deleteHit(3)

getHits ()

Return the hits array.

annotationList.getHits()

toJSON ()

Returns an object representation of the annotation list.

console.log('current annotation list is: %j', annotationList.toJSON())

AnnotationList Events

"started" (event)

Once the AnnotationList CRDT has finished the bootstrap process. You can take this opportunity to do an initial render of the list.

"mutation" (event)

Emitted whenever anything in the annotation list changes.

annotationList.on('mutation', (event) => {
  console.log('new mutation', event)
  console.log('annotation list now is:', annotationList.toJSON())
})

Callback arguments:

"add" (event)

annotationList.on('add', (event) => {
  console.log('added attribute', event.name)
  console.log('with value:', event.value)
})

Callback arguments:

"update" (event)

annotationList.on('update', (event) => {
  console.log('updated attribute', event.name)
  console.log('old value:', event.oldValue)
  console.log('new value:', event.value)
})

Callback arguments:

"delete" (event)

annotationList.on('delete', (event) => {
  console.log('deleted attribute', event.name)
  console.log('old value:', event.oldValue)
})

Callback arguments:

"resource inserted" (event)

annotationList.on('resource inserted', (event) => {
  console.log('inserted resource at pos', event.index)
  console.log('with value:', event.value)
})

Callback arguments:

"resource deleted" (event)

Callback arguments:

"hit inserted" (event)

Callback arguments:

"hit deleted" (event)

Callback arguments:

License

MIT

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

License

MIT