0045 CSS in Annotations

_includes/links.md

@@ -10,15 +10,12 @@
 [0009]: {{ site.cookbook_url | absolute_url }}/recipe/0009-book-1/ "Simple Manifest - Book"
 [0010]: {{ site.cookbook_url | absolute_url }}/recipe/0010-book-2-viewing-direction "Viewing direction and its effect on navigation"
 [0011]: {{ site.cookbook_url | absolute_url }}/recipe/0011-book-3-behavior/ "Book behavior (paging) variations"
-[0299]: {{ site.cookbook_url | absolute_url }}/recipe/0299-region/ "Addressing a spatial region"
 [0013]: {{ site.cookbook_url | absolute_url }}/recipe/0013-placeholderCanvas/ "Load a Preview Image Before the Main Content"
 [0202]: {{ site.cookbook_url | absolute_url }}/recipe/0202-start-canvas/ "Load Manifest Beginning with a Specific Canvas"
 [0014]: {{ site.cookbook_url | absolute_url }}/recipe/0014-accompanyingcanvas/ "Audio Presentation with Accompanying Image"
 [0015]: {{ site.cookbook_url | absolute_url }}/recipe/0015-start/ "Begin playback at a specific point - Time-based media"
 [0017]: {{ site.cookbook_url | absolute_url }}/recipe/0017-transcription-av/ "Providing Access to Transcript Files of A/V Content"
 
-[0139]: {{ site.cookbook_url | absolute_url }}/recipe/0139-geolocate-canvas-fragment/ "Represent Canvas Fragment as a Geographic Area on a Web Map"
-
 [0019]: {{ site.cookbook_url | absolute_url }}/recipe/0019-html-in-annotations/ "HTML in Annotations"
 [0021]: {{ site.cookbook_url | absolute_url }}/recipe/0021-tagging/ "Simple Annotation — Tagging"
 [0022]: {{ site.cookbook_url | absolute_url }}/recipe/0022-linking-with-a-hotspot/ "Redirecting from one Canvas to another resource (Hotspot linking)"
@@ -33,6 +30,7 @@
 [0031]: {{ site.cookbook_url | absolute_url }}/recipe/0031-bound-multivolume/ "Multiple Volumes in a Single Bound Volume"
 
 [0040]: {{ site.cookbook_url | absolute_url }}/recipe/0040-image-rotation-service/ "Image Rotation Two Ways"
+[0045]: {{ site.cookbook_url | absolute_url }}/recipe/0045-css/ "CSS in an Annotation"
 
 [0047]: {{ site.cookbook_url | absolute_url }}/recipe/0047-homepage/ "Linking to Web Page of an Object"
 [0046]: {{ site.cookbook_url | absolute_url }}/recipe/0046-rendering/ "Providing Alternative Representations"
@@ -49,7 +47,7 @@
 [0118]: {{ site.cookbook_url | absolute_url }}/recipe/0118-multivalue/ "Displaying Multiple Values with Language Maps"
 
 [0135]: {{ site.cookbook_url | absolute_url }}/recipe/0135-annotating-point-in-canvas/ "Annotating a specific point of an image"
-
+[0139]: {{ site.cookbook_url | absolute_url }}/recipe/0139-geolocate-canvas-fragment/ "Represent Canvas Fragment as a Geographic Area on a Web Map"
 [0154]: {{ site.cookbook_url | absolute_url }}/recipe/0154-geo-extension/ "Locate a Manifest on a Web Map"
 
 [0232]: {{ site.cookbook_url | absolute_url }}/recipe/0232-image-thumbnail-canvas/ "Implementation discussion: Thumbnails on Canvases"
@@ -66,6 +64,7 @@
 [0266]: {{ site.cookbook_url | absolute_url }}/recipe/0266-full-canvas-annotation/ "Simplest Annotation"
 [0269]: {{ site.cookbook_url | absolute_url }}/recipe/0269-embedded-or-referenced-annotations/ "Embedded or Referenced Annotations"
 [0283]: {{ site.cookbook_url | absolute_url }}/recipe/0283-missing-image/ "Missing Images in a Sequence"
+[0299]: {{ site.cookbook_url | absolute_url }}/recipe/0299-region/ "Addressing a spatial region"
 
 [0306]: {{ site.cookbook_url | absolute_url }}/recipe/0306-linking-annotations-to-manifests/ "Linking external Annotations targeting a Canvas to a Manifest"
 [0309]: {{ site.cookbook_url | absolute_url }}/recipe/0309-annotation-collection/ "Using Annotation Collections"

index.md

@@ -83,6 +83,7 @@ _(leading on to segmentation examples later)_
 * comments - various examples (51,52,54)
 * [Simplest Annotation][0266]
 * [HTML in Annotations][0019]
+* [CSS in an Annotation][0045]
 * Fragment selectors (61)
 * [Simple Annotation - Tagging][0021]
 * [Annotation with a Non-Rectangular Polygon][0261]

recipe/0019-html-in-annotations/manifest.json

@@ -47,7 +47,7 @@
           "type": "AnnotationPage",
           "items": [
             {
-              "id": "{{ id.path }}{{ id.path }}/canvas-1/annopage-2/anno-1",
+              "id": "{{ id.path }}/canvas-1/annopage-2/anno-1",
               "type": "Annotation",
               "motivation": "commenting",
               "body": {

recipe/0045-css/index.md

@@ -0,0 +1,57 @@
+---
+title: CSS in an Annotation
+id: 45
+layout: recipe
+tags: [style]
+summary: "Using an external CSS stylesheet in an annotation body, annotations can be styled in limited ways"
+viewers:
+ - Theseus
+topic:
+ - basic
+code:
+ - iiif-prezi3
+---
+
+## Use Case
+
+You have two different authors who have each made an annotation on a visual resource. You'd like to distinguish the authors visually in the presentation, putting each annotation text in a different text color.
+
+## Implementation Notes
+
+Using CSS in annotations is covered in the W3C Web Annotation Data Model. For a look at its approach to styles in Web Annotations, see [the W3C Web Annotation Data Model's Styles section](https://www.w3.org/TR/annotation-model/#styles). Note in particular changes needed to the `target` property if styling is intended for a IIIF Canvas.
+
+Annotations can be styled using CSS in three ways. This recipe focuses on using an external stylesheet. To add CSS using an external stylesheet, insert the stylesheet's URI as the the value of a `stylesheet` property on the Annotation. The `styleClass` property can then be used to reference rules in that external stylesheet, such as in the annotation `body` or composite `target` containing a `source` as well. It is advisable to set appropriate CORS headers for the stylesheet to improve its chances of working in generic viewers.
+
+Viewer behavior and the specifics of an annotation's `target` will have effects, but broadly speaking, using CSS to style the `body` of an annotation will style the content of the annotation and a CSS class in the `target` will style the annotation's highlight on a Canvas.
+
+The two other methods for adding CSS to a manifest are inline CSS and an inline stylesheet. To see how to use an inline stylesheet, see [Image Rotation Two Ways][0040]. To see how to use inline CSS, see [Visible Text Resource on a Canvas][0561]. Each of these also shows styling a IIIF resource in an annotation with a `motivation` of `painting` — that is, styling content that can be expected to be visible in the content space of a viewer.
+
+## Restrictions
+
+See the Restrictions section of the [HTML in Annotations][0019] recipe for a brief discussion of limitations to markup in annotations. These limitations can affect, in turn, the possible selectors in your external stylesheet.
+
+The CSS approach depends wholly on viewer implementation of CSS as applied to a resource. Viewers have no requirement to support CSS styling. Browser-based viewers may defer CSS implementation in whole or in part to the browser. Consequently, and also for reasons of accessibility, annotations should not rely on styling for semantics and should be readable by a human or machine without styling.
+
+One example: Since IIIF Canvas dimensions are unit-less, using pixels for text size is valid but may be interpreted variably across viewers or other clients.
+
+## Example
+
+This recipe focuses on annotations with motivations other than painting and on an external CSS stylesheet. The Theseus viewer is included here for its support of styling the annotation text, but it does not currently support styling the `target`.
+
+{% include manifest_links.html manifest="manifest.json" %}
+
+{% include jsonviewer.html src="manifest.json" config='data-line="56,60,71,78,82,93"' %}
+
+### Stylesheet
+{% include jsonviewer.html src="style.css" %}
+
+## Related Recipes
+
+* [Image Rotation Two Ways][0040], for an inline CSS stylesheet used with a IIIF resource
+* [HTML in Annotations][0019], a complementary recipe for markup, including a fuller discussion of markup use cautions
+* [Visible Text Resource on a Canvas][0561], for inline CSS used with a painted textual resource
+
+{% include acronyms.md %}
+{% include links.md %}
+
+

recipe/0045-css/manifest.json

@@ -0,0 +1,103 @@
+{
+  "@context": "http://iiif.io/api/presentation/3/context.json",
+  "id": "{{ id.url }}",
+  "type": "Manifest",
+  "label": {
+    "en": [
+      "Koto, chess, calligraphy, and painting"
+    ],
+    "ja": [
+      "琴棋書画図屏風"
+    ]
+  },
+  "items": [
+    {
+      "id": "{{ id.path }}/canvas/p1",
+      "type": "Canvas",
+      "height": 3966,
+      "width": 8800,
+      "items": [
+        {
+          "id": "{{ id.path }}/page/p1/1",
+          "type": "AnnotationPage",
+          "items": [
+            {
+              "id": "{{ id.path }}/annotation/p0001-image",
+              "type": "Annotation",
+              "motivation": "painting",
+              "body": {
+                "id": "https://iiif.io/api/image/3.0/example/reference/36ca0a3370db128ec984b33d71a1543d-100320001004/full/max/0/default.jpg",
+                "type": "Image",
+                "format": "image/jpeg",
+                "height": 3966,
+                "width": 8800,
+                "service": [
+                  {
+                    "id": "https://iiif.io/api/image/3.0/example/reference/36ca0a3370db128ec984b33d71a1543d-100320001004",
+                    "profile": "level1",
+                    "type": "ImageService3"
+                  }
+                ]
+              },
+              "target": "{{ id.path }}/canvas/p1"
+            }
+          ]
+        }
+      ],
+	  "annotations": [
+		{
+		  "id": "{{ id.path }}/page/p2/1",
+		  "type": "AnnotationPage",
+		  "items": [
+			{
+              "id": "{{ id.path }}/page/p2/anno-1",
+              "type": "Annotation",
+			  "motivation": "commenting",
+			  "stylesheet": "{{ id.path }}/style.css",
+			  "body": {
+			  	"id": "{{ id.path }}/body/sr1",
+				"type": "SpecificResource",
+				"styleClass": "author1",
+				"source": {
+			  	  "id": "{{ id.path }}/body/text1",
+				  "type": "TextualBody",
+				  "language": "en",
+				  "format": "text/html",
+				  "value": "<p>Three of the four pursuits of refined and noble men named in the screen's title are shown on this side of the screen: go, the koto, and tools for calligraphy. Each is in a container or wrapper. (GR)</p>"
+				}
+			  },
+              "target": {
+				"type": "SpecificResource",
+              	"source": "{{ id.path }}/canvas/p1#xywh=700,1250,1850,1150",
+              	"styleClass": "author1"
+              }
+			},
+			{
+              "id": "{{ id.path }}/page/p2/anno-2",
+              "type": "Annotation",
+			  "motivation": "commenting",
+			  "stylesheet": "{{ id.path }}/style.css",
+			  "body": {
+			  	"id": "{{ id.path }}/body/sr2",
+				"type": "SpecificResource",
+				"styleClass": "author2",
+				"source": {
+			  	  "id": "{{ id.path }}/body/text2",
+				  "type": "TextualBody",
+				  "language": "en",
+				  "format": "text/html",
+				  "value": "<p>The detail in the natural beauty of the setting could be seen as a contrast (or balance) to the manufactured pursuits of noble men. (TK)</p>"
+				}
+			  },
+              "target": {
+				"type": "SpecificResource",
+                "source": "{{ id.path }}/canvas/p1#xywh=170,160,2200,1000",
+                "styleClass": "author2"
+              }
+			}
+		  ]
+		}
+	  ]
+    }
+  ]
+}

recipe/0045-css/style.css

@@ -0,0 +1,11 @@
+.author1 {
+	color: #f00;
+	background-color: #fff;
+	border-color: #f00;
+}
+
+.author2 {
+	color: #1a1;
+	background-color: #fff;
+	border-color: #0f0;
+}