Configuration Guides

Rashmi Singhal edited this page Oct 29, 2015 · 30 revisions

Configuring Mirador

Without much configuration, Mirador initialises with most of its features enabled by default. To create "stripped-down" views, features may be turned off or configured to behave differently through the initial configuration options. Several of the more common configurations are described here.

For a full list of configuration options, see the Complete Configuration API page. Mirador uses the same configuration object for saving and managing its own state as you do for describing your preferences, so for an even more granular view, you can have a look at Mirador's internal default settings file. Any of these same options can be used on configuration.

Table of Contents


Getting Started

Mirador is initialised by a javascript function call. This function call takes a single argument: the javascript configuration object. You might be familiar with this pattern from using jQuery plugins.

The configuration object is just a normal javascript object, and looks something like this:

{
optionName: optionValue
// More Options ...
}

The simplest valid configuration for mirador looks like this:

 Mirador({
        id: "viewer",
        data: [
           {"manifestUri": "http://iiif/id/and/uri/of/your/manifest.json", location : "My Repository"}
        ]
      });

This will display a blank Mirador workspace with your manifest loaded into the manifest listing menu.

A blank Mirador Workspace. The user can add an object from the manifest listing at any time

The id:... property above is a string of the id attribute of the DOM element where you want to put Mirador. Mirador will fit the size of this container, so you'll need to use CSS to make it the size and shape you want Mirador to take.

The data: [...] property, which is an array, contains a list of the IIIF Manifests you want your users to have access to in Mirador. Each manifest is an object ({ ... }), and have two valid properties: manifestUri:..., and location:....

manifestUri is the URI (and @id field) of your IIIF Presentation API Manifest.

location is a string representing your image repository or institution. This will appear in the manifest listing interface so the user will know where the resource comes from.

It is important to note here that you may need to place the initialisation call inside of an "onload" handler, such as jQuery's. This will cause Mirador to initialise only after the DOM (and in particular the DOM element whose id attribute value you pass into the configuration) has finished loading.

$(function() {
  Mirador({
    // Your configuration here...
  }); 
});

Common Recipes

The three most common configurations (Full Options, Book Viewer, Zen Mode) for Mirador are listed below. More advanced kinds of configuration, as well as smaller, more specific toggles, are covered in the following sections.

Full screen with all options

One of the most common configurations is to create an HTML page in which Mirador takes up the full width and height of the page, with all of the default features activated. There are only a few required configuration options to get a fully featured Mirador instance: the container and the manifests to load into Mirador.

The Container

In order to initialize Mirador, it needs to be attached to an existing HTML div through that element's id. You also need to explicitly set that element's width and height. In this example, we are using the full width and height of the page, so we add the following css: #viewer {width: 100%; height: 100%;}.

<!DOCTYPE html>
<head>
...
  <style type="text/css">#viewer {width: 100%; height: 100%;}</style>
</head>
<body>
  // An element to contain the viewer instance.
  <div id="viewer"></div>

  <script src="build/mirador/mirador.js"></script>
  <script type="text/javascript">
    $(function() {
      Mirador({
        "id": "viewer", // The CSS ID selector for the containing element.
        "data": [ 
         ...
        ],
      });
    });
  </script>
</body>
</html>

Changing the height and width of Mirador's root element allows you place it in an HTML page with other content.

Manifests

There are a couple of different ways you can add manifests to your Mirador instance.

First you can pass objects into the data array that identify the desired manifestUri. See below.

     Mirador({
        id: "viewer",
        data: [
           {"manifestUri": "http://iiif/id/and/uri/of/your/manifest.json", location : "My Repository"}
        ]
      });

Second, you can pass in an object pointing to a collectionUri, which contains a list of manifests that Mirador will parse. See below.

     Mirador({
        id: "viewer",
        data: [
           {"collectionUri": "http://iiif/id/and/uri/of/your/collection.json"}
        ]
      });

Note that, at the present, Mirador can only parse collections that are one level deep. So if your collection data is a collection of collections, Mirador will not be able to find your manifests. Supporting more complicated collections is on the Mirador roadmap.

Within the application, there are two other ways for end users to add manifests to Mirador:

  1. If showAddFromURLBox has not been disabled, an end user can add a known IIIF manifest URL through the Add new object from URL box Object listing page

  2. Mirador can handle an end user dropping a IIIF manifest into a window using IIIF Drag-and-drop drag_and_drop

Common Additional Configurations

When using the full-screen full-featured configuration, many deployers' next questions are:

  • How do I enable Mirador's annotation feature?
  • How do I save and share the current workspace of a Mirador instance?
  • How do I open more than one window on load?
  • How do I describe the layout of windows?

Specifying Which Manifest Will Open

By default, Mirador is configured to open with a single window. You can specify which manifest will be open in that window by using the windowObjects key. The windowObjects key expects an array of objects. Within the object you can name the manifest that will be opened with loadedManifest and even specify which canvas the viewer will focus on with canvasID. The default view, however, is the ThumbnailsView viewType, so if you want the viewer to open with the ImageView rather than the ThumbnailsView view, you need specify as such with "viewType" : "ImageView" as seen in the example below. Other options that can be added to windowObjects can be found in the Complete Configuration API.

     Mirador({
       ...
       "windowObjects" : [
          {
          "loadedManifest" : "http://iiif/id/and/uri/of/your/manifest.json", 
          "canvasID" : "http://iiif/id/and/uri/of/your/canvas/canvas-id", 
          "viewType" : "ImageView"}
        ]
      }); 

Book Viewer

Similar to the previous section, this configuration provides a minimal, zooming book reader, similar to the Internet Archive Bookreader. The instance is configured to show a specific book of the developer's choosing, displayed in a 2-page spread.

Mirador({
       ...
       "windowObjects" : [
          {
          "loadedManifest" : "http://iiif/id/and/uri/of/your/manifest.json", 
          "canvasID" : "http://iiif/id/and/uri/of/your/canvas/canvas-id", 
          "viewType" : "BookView"}
        ]
      });

Describing Layouts

By default, Mirador opens with a single window. However, it is possible to configure Mirador to open up with any number of windows, positioned in a grid, using the layout option. If you want to specify which window a specific manifest loads into, use slotAddress in windowObjects. Otherwise, Mirador, will arbitrarily load objects into windows based on a first-come, first-served basis. To create an instance of Mirador that opens two windows side by side and places a manifest in each window:

     Mirador({
        id: "viewer",
        layout: "1x2",
        data: [
           {"manifestUri": "http://iiif.lib.harvard.edu/manifests/drs:5981093", "location" : "Harvard University"},
           {"manifestUri": "http://iiif.biblissima.fr/manifests/ark:/12148/btv1b84539771/manifest.json", "location":"BnF"}
        ],
 "windowObjects": [
            {
             "loadedManifest" : "http://iiif.lib.harvard.edu/manifests/drs:5981093",
             "slotAddress" : "row1.column1",
             "viewType" : "ImageView"
            },
            {
             "loadedManifest" : "http://iiif.biblissima.fr/manifests/ark:/12148/btv1b84539771/manifest.json",
             "slotAddress" : "row1.column2",
             "viewType" : "ImageView"
            }
         ]
      });

![Comparison Layout in Mirador] (https://cloud.githubusercontent.com/assets/2371632/10763681/49c0f014-7ca1-11e5-8065-89edb957a78a.png)

It is also possible to have non-grid layouts in Mirador. You can create these custom layouts using a drop down menu in Mirador:

layout drop down menu ![custom layout](https://cloud.githubusercontent.com/assets/2371632/10764293/d307c116-7ca3-11e5-9135-04829b704e0e.png)

Zen Mode

A very barebones version of the viewer can be created by turning off the top menubar and a number of the window-level options. Doing so prevents the user from opening other objects, spawning more workspace slots or windows, and closing the current window. For example:

a "Zen Mode" configuration

The configuration and initialisation for this mode looks like this:

Mirador({
        "id": "viewer",
        "mainMenuSettings" : {
          'show' : false
        },
        "data": [
           {"manifestUri": "http://iiif/id/and/uri/of/your/manifest.json",
            "location": "My Repository"}
          // For a working example, try...
          // {"manifestUri": "http://dms-data.stanford.edu/data/manifests/Walters/qm670kv1873/manifest.json",
          //  "location": "Stanford University"}
        ],
        "windowObjects": [
              {
               "loadedManifest": "http://same/iiif/id/as/above/to/your/manifest.json",
               "canvasID" : "http://iiif/id/and/uri/of/your/canvas/canvas-id",
                // For the example above:
                // "loadedManifest": "http://dms-data.stanford.edu/data/manifests/Walters/qm670kv1873/manifest.json",
               // "canvasID" : "http://dms-data.stanford.edu/data/manifests/Walters/qm670kv1873/canvas/canvas-1"
               "viewType" : "ImageView",
               "displayLayout": false,
               "bottomPanel" : false,
               "sidePanel" : false,
               "annotationLayer" : false
             }
           ]
      });

Opening onto the Object Listing Page

Specifying Open Windows in the Workspace

Embedding

iframe

In order to embed a Mirador instance in an iframe, create full screen instance with any configuration options you need. Your iframe element will look something like this:

<iframe title="Mirador" src="URL to Mirador instance" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"></iframe>

You can size and style the iframe as you need to, and Mirador will exist within its bounds. Adding the *allowfullscreen attributes allow the full screen option in Mirador to work. Of course, if you choose to disable this in Mirador, you don't need to have these attributes in your iframe.

Within the Same Page (Multiple Instances)

Advanced

Adding Buttons to the Menu Bar

Additional buttons can be added to Mirador via a userButtons setting in the configuration object. This setting defaults to null, but can be set to an Array of Objects representing links to be added to the menu.

These objects can have the following properties:

Property Description
label (required) text label assigned to the link created
attributes HTML attributes to add to the <a> tag. If there is a callback attribute for this button, this MUST exist and MUST contain an id value.
li_attributes HTML attributes to add to the <li> tag for this button.
iconClass An HTML class or space-separated list of classes. If present, an empty span with said classes will be prepended to the contents of the <a> tag within the button.
sublist a sublist of buttons, with the same structure as the primary list. Used for implementing dropdowns and other submenus
ul_attributes If the button contains a sublist, this contains attributes to attach to the <ul> tag for that sublist. Otherwise ignored
callback boolean value - if true, an error will be thrown if the button doesn't contain an id property.

As an example, here's an abridged version of the relevant configuration in use at Harvard as of 2015-9-10:

Mirador({
  "mainMenuSettings" : {
      "userButtons": [
        {"label": "Help",
         "iconClass": "fa fa-question-circle",
         "attributes": { "class": "help", "href": "http://nrs.harvard.edu/urn-3:hul.ois:hlviewerhelp"}},
        {"label": "Cite",
         "iconClass": "fa fa-quote-left",
         "attributes": { "class": "cite", "href": "#no-op"}},
        {"label": "Related Links",
         "iconClass": "fa fa-link",
         "attributes": { "class": "links", "href": "#no-op"}},
      ]
    }
});

Which produces the following HTML added to Mirador's main menu:

<ul class="user-buttons mirador-main-menu">
  <li>
    <a class="help" href="http://nrs.harvard.edu/urn-3:hul.ois:hlviewerhelp">
      <span class="fa fa-question-circle">
      </span> Help
    </a>
  </li>
  <li>
    <a class="cite" href="#no-op">
      <span class="fa fa-quote-left">
      </span> Cite
    </a>
  </li>
  <li>
    <a class="links" href="#no-op">
      <span class="fa fa-link">
      </span> Related Links
    </a>
  </li>
</ul>

Adding a Logo or Title to the Menu Bar

Adding a user-logo is quite similar to creating a user-button except that it expects an object rather than an array. So after you've finished adding your custom buttons you can add your logo like this:

Mirador({
  "mainMenuSettings" : {
    "userButtons": [
       {"label": "Help",
        "iconClass": "fa fa-question-circle",
        "attributes": { "class": "help", "href": "http://nrs.harvard.edu/urn-3:hul.ois:hlviewerhelp"}},
       {"label": "Cite",
        "iconClass": "fa fa-quote-left",
        "attributes": { "class": "cite", "href": "#no-op"}},
       {"label": "Related Links",
        "iconClass": "fa fa-link",
        "attributes": { "class": "links", "href": "#no-op"}},
      ],
    "userLogo": {
        "label": "Sentences Commentary Text Archive Image Viewer", 
        "attributes": { "id": "scta-logo", "href": "http://scta.info"}
     }
   }
 });

A couple of working examples can be found here:

Setting Limits on User Interaction (Common Features to Turn On and Off)

Controlling Mirador Dynamically

Theming

Adding Tools or Functionality

Creating Modules

Reacting to Internal Events

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.