Edirom Annotation View Web Component

Overview

The edirom-annotation-view is a Web Component used within the Edirom system to display a list of annotations and their individual detail views. It renders annotations from structured JSON data, supporting navigation between a list page and a single-annotation detail page with source previews.

It supports two layout modes: desktop and mobile. In desktop mode annotations are presented as a table; in mobile mode they appear as tappable cards with a detail view that includes source image or text previews.

Features

• Two-Page Navigation: Switches between an annotation list page (annotations) and a single annotation detail page (annotation).
• Responsive Layout: desktop mode renders a structured table; mobile mode renders cards with a detail view including source previews.
• Image Server Support: Annotation previews support both IIIF (OpenSeadragon) and Digilib image server URL formats.
• Scroll Restoration: Restores the scroll position of the annotations list when navigating back from the detail view.
• Back Navigation Hook: Listens for a back-request event from the host application and intercepts it to navigate from the detail page back to the list.

Endpoints (Attributes and Properties)

annotations-data (Attribute / Property)

The full list of annotations to display on the list page. Expects a JSON string (as an attribute) or a JavaScript array (as a property).

Expected Value Template:

[
  {
    "id": "annotation-1",
    "pos": "1",
    "title": "Annotation title",
    "categories": "Category A",
    "priority": "1",
    "sigla": "Q1"
  }
]

• id: Unique identifier for the annotation.
• pos: Position label (e.g., measure number or sequential index) displayed in the left column of each card.
• title: Annotation title shown in bold.
• categories: Category string displayed in the details row.
• priority: Priority level shown in the details row.
• sigla: Source siglum(s) shown alongside a document icon.

---

annotation-data (Attribute / Property)

The data for a single annotation to display on the detail page. Expects a JSON string (as an attribute) or a JavaScript object (as a property).

Expected Value Template:

{
  "title": "Annotation title",
  "categories": "Category A",
  "priority": "1",
  "sigla": "Q1",
  "text": "<p>Annotation body text, may contain HTML.</p>",
  "previews": [
    {
      "siglum": "Q1",
      "source": "Source name",
      "label": "m. 5",
      "type": "image",
      "digilibBaseParams": "https://image-server.example.org/iiif/3/image-id",
      "hiddenData": { "x": 100, "y": 200, "width": 300, "height": 150 }
    },
    {
      "siglum": "Q2",
      "source": "Source name",
      "label": "m. 5",
      "type": "text",
      "content": "<p>Text content rendered as HTML.</p>"
    }
  ]
}

• text: Annotation body rendered as HTML.
• previews: Array of source preview objects.
  • type: "image" to render an image preview, "text" to render HTML content.
  • For image type with openseadragon (IIIF): provide digilibBaseParams (IIIF base URL) and hiddenData (x, y, width, height for the image region).
  • For image type with digilib: provide digilibBaseParams (base URL with query params) and digilibSizeParams (region/size parameters).
  • For text type: provide content (HTML string).

---

layout-mode (Attribute / Property)

Controls the layout and rendering of the component.

Possible Values:

• desktop (default): Renders the annotations list as a plain HTML table with columns for Nr., Titel, Kategorien, Priorität, and Quelle.
• mobile: Renders the annotations list as tappable cards and includes a full annotation detail view with source previews.

---

current-page (Attribute / Property)

Controls which page is currently displayed. The attribute is kept in sync with the internal state and can be set externally to navigate programmatically.

Possible Values:

• annotations (default): Shows the annotation list.
• annotation: Shows the single annotation detail view (uses the current annotation-data).

---

image-server (Attribute / Property)

Specifies the image server type used to construct preview image URLs on the annotation detail page.

Possible Values:

• openseadragon (default): Builds IIIF Image API URLs in the format {baseUrl}/{x},{y},{width},{height}/600,/0/default.jpg.
• digilib: Builds Digilib URLs in the format {digilibBaseParams}dw=600&dh=600{digilibSizeParams}.

---

Events

annotation-selected

Dispatched (in mobile mode) when the user taps an annotation card in the list.

Event Detail:

{
  annotationData: {
    /* annotation object */
  }
}

The host application typically responds by setting annotation-data on the component and switching current-page to annotation.

Example:

document
  .querySelector("edirom-annotation-view")
  .addEventListener("annotation-selected", (e) => {
    const nav = e.target;
    nav.setAttribute(
      "annotation-data",
      JSON.stringify(e.detail.annotationData),
    );
    nav.setAttribute("current-page", "annotation");
  });

---

current-page-changed

Dispatched whenever the component switches between pages (e.g. from annotations list to annotation detail, or vice versa). Fires after the new page has been rendered.

The event is not fired on initial mount.

Event Detail:

{ value: 'annotations' | 'annotation' }

Example:

document
  .querySelector("edirom-annotation-view")
  .addEventListener("current-page-changed", (e) => {
    console.log("Page changed to:", e.detail.value);
  });

---

annotation-data-changed

Dispatched whenever the annotation-data attribute is set with a new value. This tells listeners which annotation is now being displayed (or about to be displayed) in the detail view.

Event Detail:

{ annotationData: { id: "…", pos: "…", title: "…", … } }

Example:

document
  .querySelector("edirom-annotation-view")
  .addEventListener("annotation-data-changed", (e) => {
    console.log("Annotation data changed:", e.detail.annotationData);
  });

---

back-request (Consumed)

This event is listened for by the component (not dispatched by it). When the host application dispatches a back-request event and the component is on the annotation detail page, it calls event.preventDefault() and navigates back to the annotations list page instead. If already on the list page, the event propagates normally.

---

Dependencies

edirom-icon

The edirom-annotation-view depends on the edirom-icon Web Component from the Edirom Core Web Components. It uses edirom-icon to render the document icon (description) next to the source siglum in both the annotation list cards and the detail view.

Ensure that the edirom-icon component is registered and available in your environment for the component to render correctly.

---

Styling

Mobile layout only; themed via CSS custom properties inherited into the shadow DOM. Borders, the position column background, secondary text and icons are derived from the primary colour with color-mix().

Custom property	Default	Description
--primary-color	#333333	Base colour for borders, secondary text and icons

Card backgrounds are transparent, so they take the background of the surrounding page.

Usage Example

<edirom-annotation-view
  layout-mode="mobile"
  image-server="openseadragon"
  annotations-data='[{"id":"a1","pos":"1","title":"My Note","categories":"Harmony","priority":"1","sigla":"Q1"}]'
>
</edirom-annotation-view>

<script>
  const view = document.querySelector("edirom-annotation-view");

  view.addEventListener("annotation-selected", (e) => {
    // Fetch full annotation data from your backend, then display the detail page
    view.setAttribute(
      "annotation-data",
      JSON.stringify(e.detail.annotationData),
    );
    view.setAttribute("current-page", "annotation");
  });

  // To navigate back from detail to list (e.g. from a back button):
  document.querySelector("#back-button").addEventListener("click", () => {
    view.dispatchEvent(new CustomEvent("back-request", { bubbles: true }));
  });
</script>