Frequently Asked Questions

Frequently Asked Questions

Q: How do I install Mirador?

You can install Mirador a few different ways.

The easiest way:

Add the Mirador umd build to your page.

<script src="https://unpkg.com/mirador@latest/dist/mirador.min.js"></script>

See Embedding Mirador for more about how to use this.

Requires more dependencies:

Using npm or yarn.

$ npm install --save mirador@latest
# or
$ yarn add mirador

Installing through a package manager can give you more flexibility for customization.

Q: Where can I find all of the available configuration options?

They are conveniently located in one file. See: https://github.com/ProjectMirador/mirador/blob/master/src/config/settings.js

Q: Where can I find a list of available plugins? How do I build a plugin?

See the M3 Plugins wiki page.

Q: How do I enable the elastic workspace by default?

You can setup your Mirador instance to use this by default in the config: https://codesandbox.io/s/mirador-elastic-workspace-qgcq0

Mirador.viewer({
  id: "app",
  windows: [
    {
      manifestId:
        "https://iiif.bodleian.ox.ac.uk/iiif/manifest/e32a277e-91e2-4a6d-8ba6-cc4bad230410.json"
    }
  ],
  workspace: {
    type: "elastic"
  }
});

Q: How can I control the starting position and order of windows in Mirador 3?

To do this, you will need to specify unique identifiers for your starting windows, and a workspace layout. Layout here is a binary tree structure that can be used to define the window layout. See: https://codesandbox.io/s/mirador-with-mosaic-workspace-configured-54jtk

Example

import Mirador from "mirador";

Mirador.viewer({
  id: "app",
  windows: [
    {
      id: "a",
      manifestId:
        "https://media.ng-london.org.uk/iiif/000-04SP-0000/manifest.json"
    },
    {
      id: "b",
      manifestId:
        "https://media.ng-london.org.uk/iiif/000-0176-0000/manifest.json"
    },
    {
      id: "c",
      manifestId:
        "https://media.ng-london.org.uk/iiif/000-03UK-0000/manifest.json"
    },
    {
      id: "d",
      manifestId:
        "https://media.ng-london.org.uk/iiif/000-0BW4-0000/manifest.json"
    },
    {
      id: "e",
      manifestId: "https://manifests.britishart.yale.edu/manifest/54347"
    },
    {
      id: "f",
      manifestId:
        "https://media.ng-london.org.uk/iiif/000-05LR-0000/manifest.json"
    }
  ],
  workspace: {
    layout: {
      direction: "row",
      first: {
        first: "a",
        second: "d",
        direction: "column"
      },
      second: {
        first: {
          first: "b",
          second: "e",
          direction: "column"
        },
        second: {
          first: "c",
          second: "f",
          direction: "column"
        },
        direction: "row"
      },
      splitPercentage: 33.33
    }
  }
});

Q: How can I enable "Book" view for manifests that are not specified as paged?

Configure the Mirador window settings to remove the behaviors for the view type "Book".

See https://codesandbox.io/s/mirador-with-unrestricted-view-types-my9q8?file=/src/index.js:74-218

Q: Is it possible to show search results directly, without the user typing in the search term?

Yes, initialize a window or a window config object with the defaultSearchQuery.

var miradorInstance = Mirador.viewer({
  id: 'mirador',
  windows: [{
    loadedManifest: 'https://purl.stanford.edu/fg165hz3589/iiif/manifest',
    defaultSearchQuery: 'NSF'
  }],
})

An example is here: https://github.com/ProjectMirador/mirador/blob/8318004b3e45a6b0a3e72eb83378b3dc6c259727/__tests__/integration/mirador/contentsearch.html#L18

Q: How do I programmatically set the canvas?

This can be done using Mirador's state API. A list of all of the actions are available here: https://github.com/ProjectMirador/mirador/blob/master/src/state/actions/action-types.js and this uses redux actions.

var miradorInstance = Mirador.viewer({
  id: 'mirador',
  windows: [{
    id: 'known-window-id',
    loadedManifest: 'https://iiif.harvardartmuseums.org/manifests/object/299843',
  }],
});
// We create the action first. Note we are using a specified `windowId` here. This could be accessed from the store instead of specifying upfront.
var action = Mirador.actions.setCanvas('known-window-id', 'https://iiif.harvardartmuseums.org/manifests/object/299843/canvas/canvas-43182083')
// Now we can dispatch it.
miradorInstance.store.dispatch(action);

Q: Mirador is not displaying some of the HTML or attributes from my annotations. How can I get this to display?

Mirador sanitizes the HTML per the IIIF specification. However this is configurable in the settings by changing this setting value: https://github.com/ProjectMirador/mirador/blob/master/src/config/settings.js#L234

Acceptable sanitation values are in this file: https://github.com/ProjectMirador/mirador/blob/master/src/lib/htmlRules.js

Q: My Angular project that uses Mirador 3 is not displaying thumbnails! How can I get this to work?

Angular uses a sub-project called Zone.js to monkeypatch/polyfill IntersectionObserver. IntersectionObserver is the API that Mirador uses to lazy load thumbnails.

You will need to disable the Zone.js monkeypatch. (Make sure you are on at least zone.js v0.11.2 in which this was tested with)

<script>
  __Zone_disable_IntersectionObserver = true
</script>

This is a super weird thing that it seems is unhelpfully done by Angular.

Q: How do I change the view of an image to zoom to a certain area?

This can be accomplished in a few different ways.

1. Use initialViewerConfig to set parameters on initial Mirador instance load.

You can reference our intitial-viewer-config fixture file to see an example.

If running locally, you can go the the local fixture page http://localhost:4444/__tests__/integration/mirador/viewer-config.html to see the result of setting x, y, and zoom values.

Note: this value is referenced in the viewers reducer on first load. After that it is not touched, updated, or exported in any state. It is used for the first instantiation. If you want the most recently updated values for the image position after the initial load, look under the viewers key in the state:

// The Workspace state export
....
"viewers": {
    "window-5a931c96-0bcf-4b72-8a7a-6bb4efc511b8": {
      "thumbnailNavigationPosition": "far-bottom",
      "x": 1541,
      "y": 1087,
      "zoom": 0.00035,
      "flip": false,
      "rotation": 0
    }
  },

2. Dispatching an action to update the OSD viewport (useful when outside the context of Mirador or Mirador plugins).

Given a Mirador instance, we can dispatch on action on a window that updates the OpenSeadragon viewport using Mirador's updateViewport action.

// Box to zoom to
const boxToZoom = {
  x: 1420,
  y: 1831,
  width: 800,
  height: 1195
};

const zoomCenter = {
  x: boxToZoom.x + boxToZoom.width / 2,
  y: boxToZoom.y + boxToZoom.height / 2
};
var action = Mirador.actions.updateViewport(windowId, {
  x: zoomCenter.x,
  y: zoomCenter.y,
  zoom: 1 / boxToZoom.width
});

miradorInstance.store.dispatch(action);

A full example of this is implemented here and assumes that a Mirador instance is already initialized. Note: Do not use the setTimeout method for waiting for a window to initialize. There are more appropriate redux based ways to do this.

See: https://codesandbox.io/s/mirador-dispatch-view-changes-80vym

Q: How can I customize the OpenSeadragon options used?

OpenSeadragon options can be customized by configuring the osdConfig key in the Mirador config. The default options are available here: https://github.com/ProjectMirador/mirador/blob/master/src/config/settings.js#L328-L334

var miradorInstance = Mirador.viewer({
  id: 'mirador',
  windows: [{
    loadedManifest: 'https://purl.stanford.edu/fg165hz3589/iiif/manifest'
  }]
  osdConfig: {
    maxZoomPixelRatio: 5
  }
})