45:["$","title",null,{"children":"Writing Annotorious Formatters, Pt. 1 | Rainer Simon | Observable"}] 4d:T4a8,# Writing Annotorious Formatters, Pt. 1 ## An introduction to dynamic styling in Annotorious This short tutorial series explains how you can write [formatter functions](https://recogito.github.io/annotorious/api-docs/annotorious/#formatters-1) that apply custom dynamic styles to your annotations in [Annotorious](https://annotorious.com). I split this tutorial into two parts, which cover the following topics: 1. How to write a simple formatter that changes shape color and border size, based on a tag value 2. Writing a more complex formatter that attaches labels to annotations But first things first... ### What is Annotorious? Annotorious is a JavaScript library for adding annotation functionality to images on websites. Read the introductory tutorial [here](https://observablehq.com/@rsimon/annotorious-intro), or visit the [project website here](https://annotorious.com). ### What are Formatters? __Formatters__ are a mechanism in Annotorious to create __dynamic styles__. That means: you can style annotations differently __depending on their data__. For example, if an annotation contains the tag __'important'__, you could give its border a blue glow. Let's try it!4e:T439,// Load sample annotations on Lucy, Emmet and Batman SAMPLE_ANNOTATIONS = [{ "@context":"http://www.w3.org/ns/anno.jsonld", "type":"Annotation", "id":"#ee7b49ce-13b2-4ea4-be95-85c610b94be1", "body":[{ "type":"TextualBody", "value":"important", "purpose":"tagging" }], "target":{ "selector":{ "type":"FragmentSelector", "conformsTo":"http://www.w3.org/TR/media-frags/", "value":"xywh=pixel:520,114,218,361" } } },{ "@context":"http://www.w3.org/ns/anno.jsonld", "type":"Annotation", "id":"#622e8287-1ca0-4ec8-9359-4d055611fa15", "body":[], "target":{ "selector":{ "type":"FragmentSelector", "conformsTo":"http://www.w3.org/TR/media-frags/", "value":"xywh=pixel:313,153,196,312" } } },{ "@context":"http://www.w3.org/ns/anno.jsonld", "type":"Annotation", "id":"#f2d7dfaa-d28b-420a-ad68-0f9050d41144", "body":[], "target":{ "selector":{ "type":"FragmentSelector", "conformsTo":"http://www.w3.org/TR/media-frags/", "value":"xywh=pixel:86,121,215,359" } } }]4f:[{"id":"4fba4d58380515c04baeab21a848bb599d9f066105681c99de093348de56840a8d9d62cde9355f90e67698a90a3dbef5c76c6826f1a896394f313dd2cf6441ce","href":"https://static.observableusercontent.com/files/4fba4d58380515c04baeab21a848bb599d9f066105681c99de093348de56840a8d9d62cde9355f90e67698a90a3dbef5c76c6826f1a896394f313dd2cf6441ce","name":"lego_movie_caleb_wagoner.jpg","type":"image/jpeg","lastModified":1642847674963.518,"size":49055}] 49:{"id":"d979e9462b9b64a7","slug":"writing-annotorious-formatters-pt-1","title":"Writing Annotorious Formatters, Pt. 1","thumbnail":"c4913bc5fe341892159291f631b251c09225c250d4fc57afc0485ae8cb626027","access_level":"public","create_time":"$D2022-01-20T16:25:00.010Z","update_time":"$D2022-02-04T13:00:23.473Z","view_time":null,"first_public_time":"$D2022-01-22T16:50:04.851Z","has_unpublished_edits":null,"fork":false,"stars":3,"starred":false,"owner":{"type":"team","id":"c64a718e6def143f","login":"rsimon","name":"Rainer Simon","avatar_url":"https://avatars-next.observableusercontent.com/c1e2dd298faa6623db02c1c3a62de876e64001a81c5decf0518ada3a267a70f9","tier":"starter_2024","bio":"A collector of things worth knowing and things not worth knowing.","followed_by_you":false,"follows_you":false},"version":385,"publish_version":385,"role":null,"authored":false,"authors":[{"type":"individual","id":"862fb19a86ba32ae","login":"rsimon","name":"Rainer Simon","avatar_url":"https://avatars-next.observableusercontent.com/c1e2dd298faa6623db02c1c3a62de876e64001a81c5decf0518ada3a267a70f9","tier":null,"bio":"A collector of things worth knowing and things not worth knowing.","followed_by_you":false,"follows_you":false}],"members":[{"type":"individual","id":"862fb19a86ba32ae","login":"rsimon","name":"Rainer Simon","avatar_url":"https://avatars-next.observableusercontent.com/c1e2dd298faa6623db02c1c3a62de876e64001a81c5decf0518ada3a267a70f9","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"titling":"auto","title":"Writing Annotorious Formatters, Pt. 1","cells":[{"id":231,"value":"$4d","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":11,"value":"image = FileAttachment(\"lego_movie_caleb_wagoner.jpg\").image();","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":93,"value":"__Image:__ [The LEGO Movie Press Kit](https://flic.kr/p/kthGRg) by Caleb Wagoner (Flickr, CC BY 2.0)\n

","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":87,"value":"## Writing your first formatter\n\nFormatters are JavaScript functions that take a single \nargument - the annotation object - and return a value. Different\nreturn values are possible, and will alter the style of the \nannotation in different ways. \n\nThe simplest possible return value is a __string__.\nAnnotorious will add this string to the Annotation shape's `class`\nattribute. Let's write a formatter that checks if there is an\n__important__ tag in the annotation and, if there is, adss the\nclassname __important__ to the annotations `class` attribute.\n\n### Formatter function","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":174,"value":"MyImportantFormatter = function(annotation) {\n const isImportant = annotation.bodies.find(b => {\n return b.purpose === 'tagging' && b.value.toLowerCase() === 'important'\n });\n \n if (isImportant) {\n return 'important';\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":152,"value":"### CSS rule\nBecause annotations are rendered as [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics)\nshapes, you can change their style with CSS. Let's add a CSS rule to accompany\nour formatter. The rule adds extra emphasis to the inner annotation border, if the \nannotation has the __important__ CSS class:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":264,"value":"html`\n`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":177,"value":"### Putting it all together\n\nOk, now we have:\n- A formatter function that adds an __important__ class, if the annotations contains an __important__ tag\n- A CSS rule that adds a blue border and glow to annotations that have the __important__ class\n \nWe just need to tell Annotorious to use the formatter. One way to do this\nis on startup, when initializing Annotorious:\n\n```js\n// Option 1: set formatter during init\nanno = Annotorious.init({ \n image: image,\n formatters: MyImportantFormatter\n});\n```\n\nAnother way is to set the `anno.formatters` field. You can do this at any time,\nand new styles will take effect immediately, as soon as you update the `formatters`\nfield.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":205,"value":"// Option 2: set the anno.formatters\nanno.formatters = [ MyImportantFormatter ];","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":309,"value":"## Congratulations!\nYou built your first formatter for dynamic styling in Annotorious.\n\n__All the relevant code samples above are interactive:__ try making changes to the formatter\ncode, or the CSS styles, and see how it affects the annotations in the image above. Also \n__try changing the tags__ on the annotations or __create new annotations__, and see how the \nformatter affects their style. (To delete a tag from an annotation, click the tag first, then\nclick the __X__ icon to delete it.)\n\nThat's it for now. The next tutorial will look at a more advanced technique which allows \nyou to insert __additional DOM elements__ into the annotations. \n\n[Read part 2 here](https://observablehq.com/@rsimon/writing-annotorious-formatters-pt-2).\n

","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":23,"value":"# Imports & Initialization Code\n\nThe code below is not part of the tutorial. It's just some boilerplate needed to \nmake the examples above work in this Observable notebook.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":27,"value":"// Import Annotorious as a library in this notebook\nAnnotorious = require('@recogito/annotorious@2.7.1');","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":19,"value":"// Initialize Annotorious on the sample image\nanno = Annotorious.init({ \n image: image,\n allowEmpty: true\n});","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":30,"value":"// Add some default styles for this tutorial\nhtml`\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":102,"value":"$4e","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":109,"value":"// Add sample annotations on Lucy, Emmet and Batman\nanno.setAnnotations(SAMPLE_ANNOTATIONS);","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W4f","stdlib":"1"}} 44:null