Configuration Guides
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.
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.
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...
});
});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.
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.
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 to place it in an HTML page with other content.
In this case you should also set the root element's position: relative, or it may appear that Mirador ignores its bounds.
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:
-
If
showAddFromURLBoxhas not been disabled, an end user can add a known IIIF manifest URL through theAdd new object from URLbox
-
Mirador can handle an end user dropping a IIIF manifest into a window using IIIF Drag-and-drop
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?
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"}
]
}); 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"}
]
});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:
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:
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
}
]
});To open the object listing page automatically on startup, set the openManifestsPage attribute to true and omit the windowObjects attribute.
Mirador({
id: "viewer",
data: [
{manifestUri: "https://dms-data.stanford.edu/data/manifests/Walters/qm670kv1873/manifest.json", location: "Stanford University"},
{manifestUri: "https://iiif.lib.harvard.edu/manifests/drs:5981093", location: "Harvard University"}
],
openManifestsPage: true
});To browse a nested collection's tree structure, set the manifestsPanel.module attribute to "CollectionTreeManifestsPanel" and include at least one collection-type URI in data. If the collection does not have any immediate manifest children, it's strongly recommended to select some manifests to serve as previews of what material the collection contains.
Mirador({
id: "viewer",
data: [
{ collectionUri: "https://iiif.library.utoronto.ca/presentation/v2/collections/hollar:root", location: "University of Toronto" },
{ manifestUri: "https://iiif.library.utoronto.ca/presentation/v2/hollar:Hollar_a_3000/manifest", location: "University of Toronto" },
{ manifestUri: "https://iiif.library.utoronto.ca/presentation/v2/hollar:Hollar_a_3001/manifest", location: "University of Toronto" },
{ manifestUri: "https://iiif.library.utoronto.ca/presentation/v2/hollar:Hollar_a_3002/manifest", location: "University of Toronto" }
],
manifestsPanel: {
name: "Collection tree browser",
module: "CollectionTreeManifestsPanel"
},
openManifestsPage: true
});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.
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 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:
- https://github.com/harvard-library/metadata_server/blob/master/manifests/static/manifests/dev.js#L135
- https://github.com/jeffreycwitt/mirador/blob/master/index.html#L47
- https://github.com/regisrob/demos.biblissima/blob/master/mirador/index.html#L54