2d:null 2e:["$","title",null,{"children":"Writing Annotorious Formatters, Pt. 2 | Rainer Simon | Observable"}] 33:T4a4,# Writing Annotorious Formatters, Pt. 2 ## Advanced formatters: attaching DOM elements In the second part of this two-part series (read [part 1 here](https://observablehq.com/@rsimon/writing-annotorious-formatters-pt-1)) we will dive deeper into the concept of __Formatters__ and learn how we can attach DOM elements to annotation shapes. The most popular use case for this is for creating __labels for annotations__. ### Reminder: What are Formatters? Formatters are a feature of the [Annotorious](https://annotorious.com) JavaScript library for image annotation. They are a mechanism for applying dynamic styles to annotations. That means: they change the appearance of the annotation depending on its data. You can find the API documentation for formatters [here on the Annotorious project website](https://recogito.github.io/annotorious/api-docs/annotorious/#formatters-1). ## Step-by-Step Example The image below has three annotations, each with a body that identifies the character. ```json { ... "body":[{ "type":"TextualBody", "value":"Batman", "purpose":"identifying" }], ... } ``` Let's write a formatter that attaches this body value as a label!34:T660,## Before we start: some background When working with formatter elements, it's important to understand a little bit about how Annotorious works. Annotorious uses [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) to render annotations. Annotation shapes always follow the same pattern: ```xml ``` The annotation is a `` group element that contains: - __Two identical copies of the shape__ (rectangle, polygon, circle, etc.). Why two? Two copies make it possible to create shape styles with outlines. For example, you can style the `a9s-outer` shape with black stroke and 3px width; and the `a9s-inner` shape with a white stroke and 1px width.) - __Optionally: a nested SVG element__ containing another `` group. This group will act as a container for our label. Annotorious will automatically apply scaling to this group, so that it stays at constant size in responsive images!

### Inserting SVG vs. HTML elements The essential piece of information is this: if we use a formatter to insert a DOM element, __the element will be inserted into an SVG container__. This means that __we can only insert SVG elements__!

### Using foreignObject to insert HTML It is also possible to insert HTML into an SVG container. However, this takes one extra step: we have to wrap it into a [foreignObject](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/foreignObject) first.35:T52a,// 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":"Batman", "purpose":"identifying" },{ "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":[{ "type":"TextualBody", "value":"Emmet", "purpose":"identifying" }], "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":[{ "type":"TextualBody", "value":"Lucy", "purpose":"identifying" }], "target":{ "selector":{ "type":"FragmentSelector", "conformsTo":"http://www.w3.org/TR/media-frags/", "value":"xywh=pixel:86,121,215,359" } } }]36:[{"id":"4fba4d58380515c04baeab21a848bb599d9f066105681c99de093348de56840a8d9d62cde9355f90e67698a90a3dbef5c76c6826f1a896394f313dd2cf6441ce","href":"https://static.observableusercontent.com/files/4fba4d58380515c04baeab21a848bb599d9f066105681c99de093348de56840a8d9d62cde9355f90e67698a90a3dbef5c76c6826f1a896394f313dd2cf6441ce","name":"lego_movie_caleb_wagoner.jpg","type":"image/jpeg","lastModified":1643748666644.091,"size":49055}] 31:{"id":"1c2d7d56509da154","slug":"writing-annotorious-formatters-pt-2","title":"Writing Annotorious Formatters, Pt. 2","thumbnail":"171754f68f7ac0b5bc66382a0065c3e1181def9964020e8f3bf84842a327a42e","access_level":"public","create_time":"$D2022-02-01T16:58:56.621Z","update_time":"$D2022-02-05T09:51:46.181Z","view_time":null,"first_public_time":"$D2022-02-04T12:52:34.906Z","has_unpublished_edits":null,"fork":false,"stars":2,"starred":false,"owner":{"type":"team","id":"c64a718e6def143f","login":"rsimon","name":"Rainer Simon","avatar_url":"https://avatars-next.observableusercontent.com/c1e2dd298faa6623db02c1c3a62de876e64001a81c5decf0518ada3a267a70f9","tier":"starter_2024"},"version":339,"publish_version":339,"role":null,"authored":false,"authors":[{"type":"individual","id":"862fb19a86ba32ae","login":"rsimon","name":"Rainer Simon","avatar_url":"https://avatars-next.observableusercontent.com/c1e2dd298faa6623db02c1c3a62de876e64001a81c5decf0518ada3a267a70f9","tier":null}],"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":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"title":"Writing Annotorious Formatters, Pt. 2","cells":[{"id":0,"value":"$33","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":13,"value":"image = FileAttachment(\"lego_movie_caleb_wagoner.jpg\").image()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":10,"value":"__Image:__ [The LEGO Movie Press Kit](https://flic.kr/p/kthGRg) by Caleb Wagoner (Flickr, CC BY 2.0)\n

\n\nThe image shows the final result of this tutorial. You can see the intermediate results\nby selecting from the dropdown below.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":212,"value":"viewof selected = html``","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":216,"value":"{\n if (selected == '1') {\n anno.formatters = [ MyLabelFormatter ];\n } else if (selected == '2') {\n anno.formatters = [ \n MyLabelFormatter,\n MyClassFormatter\n ];\n } else {\n anno.formatters = [ \n MyLabelFormatter,\n MyClassFormatter,\n Step3Formatter\n ];\n }\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":38,"value":"$34","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":196,"value":"# Step 1: The Formatter\n\nLet's write a formatter that does the following:\n- find the first annotation body with a purpose of `identifying`\n- if there is an `identifying` body, create an HTML __label__ element, wrapped inside a __foreignObject__","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":43,"value":"MyLabelFormatter = function(annotation) { \n // Find the label body (if any)\n const label = annotation.bodies.find(b => b.purpose === 'identifying');\n\n if (label) {\n // Return an HTML label, wrapped in an SVG foreignObject\n const foreignObject = document.createElementNS('http://www.w3.org/2000/svg', 'foreignObject');\n foreignObject.innerHTML =\n `${label.value}`;\n \n return {\n element: foreignObject\n };\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":50,"value":"### CSS rule\n\nWe also need to add some base styling for our labels to show up properly.\nThere are some issues we need to take care of:\n\n- Per default, the __foreignObject__ will have a size of 0x0 pixels. We want to make sure our label is visible. Therefore, we give it `overflow:visible`.\n- Some browsers won't render a __foreignObject__s with 0x0 size, despite visible overflow. To prevent this, we'll give it a 1px size.\n\nWe'll also apply a bit of padding __label__ itself, just for good looks. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":54,"value":"html`\n`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":250,"value":"# Step 2: Adding Some Color\n\nCongratulations! We're through the hard parts. Now it's just about refining formatting \nand styles, for extra effects. Let's give each character a different color.\n\nIn the [previous tutorial](https://observablehq.com/@rsimon/writing-annotorious-formatters-pt-1), \nwe used a formatter to add a CSS class to the annotation, and then created a style rule for this\nclass in our styleheet.\n\nLet's repeat this and add the character name as a CSS class using another formatter.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":72,"value":"MyClassFormatter = function(annotation) {\n const label = annotation.bodies.find(b => b.purpose === 'identifying');\n\n if (label) {\n return label.value;\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":286,"value":"
\nNow lets add different color borders for each character.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":292,"value":"html\n``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":94,"value":"
\n# Step 3: Label Placement\n\nPer default, the label will be placed in the upper right corner of the annotation.\nAs a final exercise, let's use CSS transforms to change the position of the label,\nso that it sits attached to the top of the annotation - and add some final color to\nthe label!\n\nThe most important part is this:\n\n```css\n.a9s-annotation label {\n transform:translateY(-100%) translateX(-1px);\n}\n```\n\nThis will\n- move the label up by it's own size (100%)\n- move the label left 1px, to align with the annotation border\n\nFinally, let's just add some extra color for the label to\nmatch the border. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":109,"value":"html\n``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":326,"value":"# Congratulations!\n\nThis concludes the two-part tutorial on Annotorious Formatters. If you have questions\nor suggestions, do drop me a line on [twitter](https://twitter.com/aboutgeo), or shout \nout on the [Annotorious support chat](https://gitter.im/recogito/annotorious). ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":18,"value":"
\n# Imports & Initialization Code\n\nThe code below is not part of the tutorial. It's just some boilerplate needed to make the examples above work in this Observable notebook.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":23,"value":"// Import Annotorious as a library in this notebook\nAnnotorious = require('@recogito/annotorious@2.7.1');","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":26,"value":"// Initialize Annotorious on the sample image\nanno = Annotorious.init({ \n image: image,\n allowEmpty: true\n});","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":29,"value":"// Add some default styles for this tutorial\nhtml`\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":32,"value":"$35","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":35,"value":"anno.setAnnotations(SAMPLE_ANNOTATIONS);","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":306,"value":"// We just use this, so we can switch 'Step 3' on and off in the example image\nStep3Formatter = function(annotation) {\n return 'step-3';\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W36","stdlib":"1","titling":"auto"}} 32:"$31:body"