CSS in an Annotation

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. 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. To see how to use inline CSS, see Visible Text Resource on a Canvas. 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 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. Even more broadly than with HTML, viewers have no requirement to support any particular approach to CSS styling or even to support CSS at all. Browser-based viewers may defer CSS implementation in whole or in part to the browser and may allow only a defined subset of CSS either for internal or for deferred application. Consequently, and also for reasons of accessibility, annotations should not rely on styling for semantics and should be meaningful to a human and parsable by machine without styling.

CSS can also be used as the vector for unethical or insecure actions. For instance, a background rule could include a tracking image in its value: background: lightblue url(http://example.com/tracker/image.jpg) no-repeat fixed center; This image could phone home data about accesses to the annotation. To be more certain of security, viewers and annotation stores that allow annotations from anonymous sources could strip any stylesheet propery entirely.

Even where a viewer supports CSS broadly, the intersection of IIIF and CSS can result in uncertainty. For instance, since IIIF Canvas dimensions are unit-less, using pixels for text size in CSS 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.

JSON-LD | View in Theseus

Code samples: Python: iiif-prezi3




Stylesheet