Manage Canvases

Reference: https://iiif.library.utoronto.ca/presentation/v2/#!/Canvas/CanvasByItemGet

Table of Contents

• Create a Canvas
• Update a Canvas
• Delete a Canvas
• View a Canvas
• FAQ

IIIF Reference: http://iiif.io/api/presentation/2.1/#canvas

Create a Canvas

• A canvas can be created by sending a POST request to {identifier}/canvas with the required parameters.
• For example:

{
  "canvas": {
    "@id": "http://example.org/iiif/book1/canvas/p5",
    "@type": "sc:Canvas",
    "label": "p. 1",
    "height": 1000,
    "width": 750,
    "thumbnail": {
      "@id": "http://example.org/iiif/book1/canvas/p1/thumb.jpg",
      "@type": "dctypes:Image",
      "height": 200,
      "width": 150
    },
    "images": [
      {
        "@type": "oa:Annotation",
        "motivation": "sc:painting",
        "stylesheet": {
          "@type": [
            "oa:CssStyle",
            "cnt:ContentAsText"
          ],
          "chars": ".red {color: red;}"
        },
        "resource": {
          "@id": "https://dlcs.io/iiif-img/default.jpg",
          "@type": "oa:SpecificResource",
          "style": "red",
          "format": "image/jpeg",
          "full": {
            "@type": "cnt:ContentAsText",
            "chars": "Rubrics are Red, ..."
          }
        },
        "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,150,500,30"
      }
    ],
    "otherContent": [
      {
        "@id": "http://example.org/iiif/book1/list/p1",
        "@type": "sc:AnnotationList"
      }
    ]
  }
}

• This would create the sequence for the identifier book1 with name p5 and also create all of its provided sub-annotations and annotationLists recursively.
• Each sub-annotation and annotationList will have an upward link to this canvas defined in their belongsTo field with this canvas @id.
• The new canvas will also have a list of @ids in its children field. This value along with the belongsTo are later used to re-construct the canvas when viewing.
• Suppose any of the sub-annotation or annotationList already exists, those objects will be updated with any new values from this request. Those objects will also be updated to have their belongsTo field to contain this new canvas @id.

Update a Canvas

• A canvas can be updated by sending a PUT request to /{identifier}/canvas/{name} with fields that need to be updated.
• Updating a canvas without any of its sub-annotations or annotationLists in the request body would not affect its children unless the @id is being changed. In this case, an internal update will be performed on all of its children to update their belongsTo values.
• Suppose any of the sub-annotation or annotationList does not exist, those objects will be created with new values from this request. Those objects will also be updated to have their belongsTo field to contain this new canvas @id.

Delete a Canvas

• A canvas can be deleted by sending a DELETE request to /{identifier}/canvas/{name}. Beware that this will also delete all sub-annotations and annotationLists under this canvas recursively.

View a Canvas

• A single canvas can be viewed at /{identifier}/canvas/{name}. This lists all sub-annotations and annotationLists that have the requested canvas @id in their belongsTo field.

FAQ

• How to create a canvas without an @id?

• A POST with no @id in the request body will auto-generate a unique UUID name for that object with the provided identifier.

• How to hide a specific sub-annotation or annotationList when viewing a canvas ?

• This can be achieved by sending a PUT request to the object that needs to be hidden by updating the hidden property to true.

{"annotation: {"hidden": true}} or {"annotationList: {"hidden": true}}

• How to change the order of sub-annotations or annotationLists of a parent canvas?
• This can be achieved by sending a PUT request to the parent canvas with the correct order of @ids for sub-annotations and annotationLists.
• This would auto-update the order field of all the sub-annotations and annotationLists.

{"canvas": {
 "images": [{"@id": "id-of-annotation-1"}, {"@id": "id-of-annotation-2"}], 
 "otherContent": [{"@id": "id-of-annotationList-1"}, {"@id": "id-of-annotationList-2"}]
}}