Skip to content

Settings

Jump to bottom Edit New page
Eric Liu edited this page Aug 10, 2018 · 23 revisions

Diva.js uses a number of variables that behave like instance variables but are instead stored in a private settings object. Some can be set by the user, as explained in the User-configurable settings section below. Others cannot be modified by the user when creating the document viewer, as their default values may be necessary for the document viewer for work; these settings are listed in the Other settings section.

These settings are all referenced in the form settings.variableName within the actual code. For instance, to access or change the fixedPadding while in diva.js (or from a plugin), use settings.fixedPadding (or this.core.settings.fixedPadding, respectively).

These are settings that can be specified by the user when creating the diva.js instance. They are found in the options array. All of them have values that they default to if they are not specified by the user; however, some settings need to be configured for the document viewer to function properly.

These settings can be set upon instantiating the document viewer, in the following format:

let diva = new Diva('diva-wrapper', {
    objectData: "manifest.json",
    settingName: "some string",
    anotherSettingName: false,
    anotherNotherSettingName: 0.05,
    // ...
});

These settings can be accessed through the core object for plugins, or directly through the Diva instance (if provided).

// plugins
let settings = this.core.settings;
// in diva.js
this.settings;
// in viewer-core.js
this.publicInstance.settings;

Required settings:

Find the full list of such settings below.

User-configurable Settings

acceptHeader

  • Required: No
  • Default value: "application/json"
  • Comment (in the code): The header to send off to the server in content negotiation

A string which specifies what header to send off to the server in content negotiation (for IIIF manifests).

adaptivePadding

  • Required: No
  • Default value: 0.05
  • Comment (in the code): The ratio of padding to the page dimension

A float, between 0 and 1, that determines the padding between pages (vertically) and around the edges of pages (horizontally) based on the average height and width of the pages in the document. For instance, if set to 0.05, horizontal padding will be 5% of the average width and vertical padding will be 5% of the average height. Note that if there are any plugins with icons enabled, the vertical padding will be at least 40 pixels to make room for the icons above each page.

To disable adaptive padding and instead used a fixed padding per page, set this to 0; the fixed padding per page can then be set in settings.fixedPadding.

arrowScrollAmount

  • Required: No
  • Default value: 40
  • Comment (in the code): The amount (in pixels) to scroll by when using the arrow keys

An integer that specifies the scroll amount when settings.enableKeyScroll is set to true. If enableKeyScroll is false, the arrow keys defer to default browser behavior and this setting has no effect.

blockMobileMove

  • Required: No
  • Default value: true
  • Comment (in the code): Prevent moving or scrolling the page on mobile devices

By default, users viewing the document from a touch device (e.g. an iPad) are unable to move the webpage, to give it more of an app-like feel. This also results in users being unable to scroll the page, which is fine if the document viewer is the only element on the page; if this is not the case, then this behaviour is undesired, in which case it can be disabled by setting blockMobileMove to false.

objectData

  • Required: Yes
  • Default value: none
  • Comment (in the code): URL to the IIIF manifest.

The URL to the IIIF manifest.

objectData can be a JSON object instead of a URL to a IIIF manifest; you can write your own JSON manifests and have objectData point to this file.

Format:

let diva = new Diva('diva-wrapper', {
    objectData: "http://example.com/manifest.json"
    // or
    objectData: "path/to/manifest.json"
});

enableAutoTitle

  • Required: No
  • Default value: true
  • Comment (in the code): Shows the title within a div of id diva-title

If set to true, Diva displays the title (the manifest label) above the document viewer. The title is a div element with id diva-?-title (where ? is the number of the document viewer, 1-indexed). This probably only needs to be set to false if you don't want the title to appear at all, or want it to appear somewhere completely different in the document, or want to add something before or after the title; for the latter cases, you can get the title of the document using the getItemTitle() method. If you just want to change the appearance of the title you can easily do so through CSS, by targeting the 'diva-title' class.

enableFilename

  • Required: No
  • Default value: true
  • Comment (in the code): Uses filenames and not page numbers for links (i=bm_001.tif, not p=1)

If set to true, the p hash parameter will be disabled and the viewer will instead make use of the i hash parameter, which uses the filename. For instance, to go to the second page, one would have to specify i=bm_002.tif instead of p=2.

enableFullscreen

  • Required: No
  • Default value: true
  • Comment (in the code): Enable or disable fullscreen icon (mode still available)

Enable or disable the appearance of the fullscreen icon, which toggles fullscreen mode. If set to false, the icon will not appear, but it will still be possible to toggle fullscreen mode through the public functions and the f hash parameter.

enableGotoPage

  • Required: No
  • Default value: true
  • Comment (in the code): A "go to page" jump box

When true, a "Go to page" input field is displayed in the upper right corner. It can be used can enter a page number to jump to (shown in the screenshot below):

Screenshot

enableGridIcon

  • Required: No
  • Default value: true
  • Comment (in the code): A grid view of all the pages

Not functional in Diva 6. Set to true if you want to enable the icon for toggling grid view. If this is set to false, the icon will not appear but it will still be possible to toggle grid view using the public functions and the g hash.

enableGridControls

  • Required: No
  • Default value: 'buttons'
  • Comment (in the code): Specify control of pages per grid row in Grid view. Possible values: 'buttons' (+/-), 'slider'. Any other value disables the controls.

Not functional in Diva 6. Sets the type of (or deactivates) the "pages per row" control in grid view. Can be set to 'buttons' to display plus and minus buttons, 'slider' to display a pages-per-row slider, or 'none' to not display any control. If set to 'none', then it's not possible to change the number of pages per row except through the n hash parameter.

enableImageTitles

  • Required: No
  • Default value: true
  • Comment (in the code): Adds "Page {n}" title to page images if true

Not functional in Diva 6. If set to true, will enable a numbering based page title above each page image.

enableKeyScroll

  • Required: No
  • Default value: true
  • Comment (in the code): Captures scrolling using the arrow and page up/down keys regardless of page focus. When off, defers to default browser scrolling behavior.

When set to true, the user can scroll through the document by using the arrow, page up, and page down keys anywhere on the page. This overrides the default arrow and page up/down keys behaviour of scrolling the page (as opposed to the document viewer), and can be disabled if desired (i.e. if there is other content on the webpage that the user may wish to scroll).

enableSpaceScroll

  • Required: No
  • Default value: false
  • Comment (in the code): Scrolling down by pressing the space key

When set to true, pressing the spacebar scrolls the document viewer rather than the entire webpage.

enableLinkIcon

  • Required: No
  • Default value: true
  • Comment (in the code): Controls the visibility of the link icon

Not functional in Diva 6. Controls the presence of the link icon, in the top right corner. If set to false, the icon will no longer appear but the hash parameters will still work.

enableNonPagedVisibilityIcon

  • Required: No
  • Default value: true
  • Comment (in the code): Controls the visibility of the icon to toggle the visibility of non-paged pages. (Automatically hidden if no 'non-paged' pages)

Not functional in Diva 6.

enableToolbar

  • Required: No
  • Default value: true
  • Comment (in the code): Enables the toolbar. Note that disabling this means you have to handle all controls yourself by using Diva's [Public Methods].

Not functional in Diva 6. When set to true, shows the toolbar.

enableZoomControls

  • Required: No
  • Default value: 'buttons'
  • Comment (in the code): Specify controls for zooming in and out. Possible values: 'buttons' (+/-), 'slider'. Any other value disables the controls.

Not functional in Diva 6. Sets the type of (or deactivates) the zoom control in document view. Can be set to 'buttons' to display plus and minus buttons, 'slider' to display a zoom slider, or 'none' to not display any zoom control. If set to 'none', then the user can still zoom in and out, but can only do it through double-clicking (or pinch-zooming on a touch device).

fillParentHeight

  • Required: No
  • Default value: true
  • Comment (in the code): Use a flexbox layout to allow Diva to fill its parent's height

When set to true, Diva will use a flexbox layout to fill its parent's height. For wider browser support, it might be useful to disable this by setting this to false.

fixedPadding

  • Required: No
  • Default value: 10
  • Comment (in the code): Fallback if adaptive padding is set to 0

The number of pixels of padding between pages and on the left and right sides of pages. Only used if settings.adaptivePadding is set to 0. If the width of the pages is sufficiently smaller than the width of the document viewer, then the width will vary; however, this setting will always dictate the minimum width when adaptive padding is set to 0.

fixedHeightGrid

  • Required: No
  • Default value: true
  • Comment (in the code): So each page in grid view has the same height (only widths differ)

If set to true, all images will have the same height in grid view. If set to false, they will all have the same width. If you know that all of your images have the exact same dimensions, then this setting doesn't matter and they will all have the same width and height. If one or more of the images is significantly wider than the rest, then you may wish to set this to false; otherwise, keep it at true.

Here is an example of a document with one page significantly wider than the rest, with fixedHeightGrid set to false:

Screenshot

The alternative for this document would be to set it to true, resulting in the following sparse-looking grid:

Screenshot

goDirectlyTo

  • Required: No
  • Default value: 0
  • Comment (in the code): Default initial page to show (0-indexed)

This determines the first page that is shown when loading the document viewer. It is zero-indexed, so to load page number 10 (as seen in the page number label on Diva), set this to 9. Overridden by the p or i hash parameters (see settings.enableFilename).

hashParamSuffix

  • Required: No
  • Default value: ''
  • Comment (in the code): Used when there are multiple document viewers on a page

Allows customization of the hash params used to generate a custom URL to recreate the current view. Useful when a single page application deletes and re-instantiates multiple Diva viewers.

inFullscreen

  • Required: No
  • Default value: false
  • Comment (in the code): Set to true to load fullscreen mode initially

Set to true to enter fullscreen mode initially (upon page load). Can be overridden if the f hash parameter is set to false.

inBookLayout

  • Required: No
  • Default value: false
  • Comment (in the code): Set to true to load book view initially

Set to true to enter book layout view initially (upon page load). Can be overridden if the v hash parameter is set to something other than b.

inGrid

  • Required: No
  • Default value: false
  • Comment (in the code): Set to true to load grid view initially

Set to true to enter grid view initially (upon page load). Can be overridden if the v hash parameter is set to something other than g.

maxPagesPerRow

  • Required: No
  • Default value: 8
  • Comment (in the code): Maximum number of pages per row, grid view

Controls the maximum number of pages per row to display in grid view. Should be equal to or greater than settings.minPagesPerRow. If it is not, it will be set to settings.minPagesPerRow(#minpagesperrow). This value is used by the grid slider and when validating the n hash parameter.

maxZoomLevel

  • Required: No
  • Default value: -1
  • Comment (in the code): Optional; defaults to the max zoom returned in the JSON response

Controls the maximum zoom level in document view. Should be equal to or less than the actual largest zoom level of the document. If it is not, it will be set to this level. This value is used by the zoom controls and when validating the z hash parameter.

minPagesPerRow

  • Required: No
  • Default value: 2
  • Comment (in the code): 2 for the spread view. Recommended to leave it

Controls the minimum number of pages per row to display in grid view. Should be at least 2 (if not, will be set to 2). This value is used by the pages-per-row control in grid view and when validating the n hash parameter.

minZoomLevel

  • Required: No
  • Default value: 0
  • Comment (in the code): Defaults to 0 (the minimum zoom)

Controls the minimum zoom level in document view. This must be greater than or equal to 0 and less than settings.maxZoomLevel (or equal to it, if you wish to disable zooming entirely).

onGotoSubmit

  • Required: No
  • Default value: null (uses the function gotoPageByLabel)
  • Comment (in the code): When set to a function that takes a string and returns a page index, this will override the default behaviour of the 'go to page' form submission

Used to override the default behaviour of the 'go to page' form in the toolbar. Might be good to use in conjunction with the setting enableGotoSuggestions.

pageAliases

  • Required: No
  • Default value: {}
  • Comment (in the code): An object mapping specific page indices to aliases (has priority over pageAliasFunction)

Not functional in Diva 6. Page aliases can be defined through this setting and the pageAliasFunction setting. The page aliases are shown in the toolbar instead of the page number, and can be used in public methods such as gotoPageByAliasedNumber. Specify page aliases in the following format:

{0: 'i', 1: 'ii', 2: 'iii'}

It is not necessary to provide a mapping for all the pages in the document. If a page index does not match a mapping in this setting and the pageAliasFunction returns false when passed this page index, then the page number (1-indexed) is returned.

pageAliasFunction

  • Required: No
  • Default value: function(pageIndex) { return false; }
  • Comment (in the code): A function mapping page indices to an alias. If false is returned, default page number is displayed

Not functional in Diva 6. This function should accept a page index, and return a page alias (a string). If this method returns false, the default page number will be displayed in the toolbar and used as an alias. More info in the above setting pageAliases.

pageLoadTimeout

  • Required: No
  • Default value: 200
  • Comment (in the code): Number of milliseconds to wait before loading pages

Not functional in Diva 6. The number of milliseconds to wait before loading a page after first determining that the page should be loaded. This timeout is useful in preventing unnecessary page loads, such as when a user is scrolling quickly through a document and doesn't wish to load all the intermediate pages that are being scrolled past.

A longer timeout results in fewer pages unnecessarily loaded, but can result in scrolling that feels less smooth and pages taking longer to load (from the user's point of view). A shorter timeout results in pages loading more immediately, but scrolling through the document can lead to many more images being downloaded than is necessary. Since the downloads are enqueued, subsequent page loads can be significantly slower. The default value has been tested on faster connections and seems to be a good middle ground, but it may not be optimal for slower connections, or for particular documents; in that case, you may wish to play around with the value until you can find one that is optimal.

pagesPerRow

  • Required: No
  • Default value: 5
  • Comment (in the code): The default number of pages per row in grid view

The default number of pages to display per row in grid view. The width of each page in grid view is equal to the width of the document viewer's outer panel divided by pagesPerRow.

showNonPagedPages

  • Required: No
  • Default value: false
  • Comment (in the code): Whether pages tagged as 'non-paged' (in IIIF manifests only) should be visible after initial load

throbberTimeout

  • Required: No
  • Default value: 100
  • Comment (in the code): Number of milliseconds to wait before showing throbber

The number of milliseconds to wait for the AJAX request (for the information about the document, specifically the objectData JSON) to be returned before showing a throbber (loading indicator icon) in the middle of the document viewer pane, as in the following screenshot:

Screenshot

This is useful if a user is on a slow network connection or if the image server is slow to respond.

tileHeight

  • Required: No
  • Default value: 256
  • Comment (in the code): The height of each tile, in pixels; usually 256

The height of the individual tiles that make up page images, in pixels. This is configured when processing the images into tiled images using either [[process.py|Preparing Your Images]] or other image processing tools. Usually tiles are 256x256, but if you have nonstandard tile sizes then you can change this.

tileWidth

  • Required: No
  • Default value: 256
  • Comment (in the code): The width of each tile, in pixels; usually 256

The width of the tiles, in pixels. See settings.tileHeight.

toolbarParentObject

  • Required: No
  • Default value: null

The toolbar parent object. If you wish the toolbar to be located in a separate element from the document viewer, set this value to the desired element. If set to null, it defaults to the primary Diva element.

Format:

let diva = new Diva({
    // ...
    toolbarParentObject: DOMElement,
    // ...
});

verticallyOriented

  • Required: No
  • Default value: true
  • Comment (in the code): Determines vertical vs. horizontal orientation

This setting indicates whether pages in document view are layed out vertically or horizontally. When set to true, the user scrolls downwards to view the next page in document view. When set to false, the user scrolls to the right to view the next page.

viewportMargin

  • Required: No
  • Default value: 200
  • Comment (in the code): Pretend tiles +/- 200px away from viewport are in

The distance beyond the edge of the viewport to be counted as "within for the viewport" when loading images. Increasing this value results in slightly smoother scrolling, but can increase the amount of data transferred unnecessarily (and thus result in image loading delays when scrolling through the document). The default value of 200 was chosen because it provides a good balance between smooth scrolling and preventing unnecessary data transfer.

zoomLevel

  • Required: No
  • Default value: 2
  • Comment (in the code): The initial zoom level (used to store the current zoom level)

The initial zoom level. If the zoom controls have been enabled, then this is the value the controls label will show. If this value does not lie between settings.minZoomLevel and settings.maxZoomLevel, then settings.minZoomLevel will be used for the initial zoom level.

Other Settings

These are members of the settings object that can't be changed when initialising a viewer. They can, however, be accessed from within a plugin.

currentPageIndex

  • Initial value: 0
  • Comment (in the code): The current page in the viewport (center-most page)

This is used to store the number (with 0-based indexing) of the page considered the "current" page, so that it can be displayed to the user. If more than one page is visible at a given time, then the current page is determined according to the scroll direction; see [setCurrentPage()] for more information.

horizontalOffset

  • Initial value: 0
  • Comment (in the code): Used in documentScroll for scrolling more precisely

Used by gotoPage: if, upon reload, the document viewer needs to display a certain page at a certain horizontal position (i.e. the user has double-clicked to zoom into a certain area or has been sent a link to that section of the page), horizontalOffset determines that offset. It is relative to the page (i.e. not including content to the left or right of the current page). If you need to translate a horizontal offset into an offset that includes content other than the current page, use pageLeftOffsets or horizontalPadding depending on whether you are in [vertical or horizontal orientation].

horizontalPadding

  • Initial value: 0
  • Comment (in the code): Either the fixed padding or adaptive padding

See settings.fixedPadding and settings.adaptivePadding for details on how this is calculated.

ID

  • Initial value: null
  • Comment (in the code): The prefix of the IDs of the elements (usually 1-diva-)

This is used to accommodate multiple document viewers on a page. The first (or only) document viewer on the page will have a prefix of 1-diva; subsequent document viewers will have prefixes of 2-diva, 3-diva, etc. This means that any element created in the DOM will look something like this (replacing 1 with the actual document viewer number):

<div id="1-diva-something"></div>

This is to ensure that all the elements have unique IDs (as is required for the HTML to be valid), even if there are multiple instances of diva.js on the page.

See also settings.selector.

initialKeyScroll

  • Initial value: false
  • Comment (in the code): Holds the initial state of enableKeyScroll

initialSpaceScroll

  • Initial value: false
  • Comment (in the code): Holds the initial state of enableSpaceScroll

innerElement

  • Initial value: null
  • Comment (in the code): The native .diva-outer DOM object

innerObject

  • Initial value: {}
  • Comment (in the code): document.getElementById(settings.ID + 'inner'), for selecting the .diva-inner element

isActiveDiva

  • Initial value: true
  • Comment (in the code): In the case that multiple diva panes exist on the same page, this should have events funneled to it.

isIIIF

  • Initial value: false
  • Comment (in the code): Specifies whether objectData is in Diva native or IIIF Manifest format

isScrollable

  • Initial value: false
  • Comment (in the code): Used in enable/disableScrollable public methods

isZooming

  • Initial value: false
  • Comment (in the code): Flag to keep track of whether zooming is still in progress, for handleZoom

loaded

  • Initial value: -1
  • Comment (in the code): A flag for when everything is loaded and ready to go.

True once all initial viewer loading and setup is complete. Used by the [[checkLoaded()|Private functions#checkloaded]] function to prevent public functions from being called when there is not yet any corresponding data to return.

mobileWebkit

  • Initial value: false
  • Comment (in the code): Checks if the user is on a touch device (iPad/iPod/iPhone/Android)

This setting is determined by checking if window.orientation is defined. If so, then the device is probably some sort of mobile or tablet device. The name mobileWebkit was chosen because all of the testing was done on iOS and Android, but this setting should cover those using other mobile/tablet devices as well.

numPages

  • Initial value: 0
  • Comment (in the code): Number of pages in the array

Taken from the generated JSON objectData. The total number of pages in the document.

oldZoomLevel

  • Initial value: -1
  • Comment (in the code): Holds the previous zoom level after zooming in or out

outerElement

  • Initial value: ''
  • Comment (in the code): The native .diva-outer DOM object

outerObject

  • Initial value: ''
  • Comment (in the code): document.getElementById(settings.ID + 'outer'), for selecting the .diva-outer element

pageTools

  • Initial value: ''
  • Comment (in the code): The string for page tools

More specifically, this holds the HTML (as a string) of the .diva-page-tools div. If no plugins with a handleClick() method are enabled, then this will be an empty string. Otherwise, it will contain the HTML necessary to create an icon for that plugin.

For example, if exactly one plugin (called info) were enabled, then settings.pageTools would look like this:

<div class="diva-page-tools"><div class="diva-info-icon" title="Title"></div></div>

The above would be appended to each page div, immediately before the first tile div.

parentObject

  • Initial value: DOMElement
  • Comment (in the code): DOM object referencing the parent element

pendingManifestRequest

  • Initial value: null
  • Comment (in the code): Reference to the xhr request retrieving the manifest. Used to cancel the request on destroy()

plugins

  • Initial value: []
  • Comment (in the code): Filled with the enabled plugins from window.divaPlugins

This array of objects holds all initialized plugins. Diva uses it to run plugins' init methods on the initial load, and to bind click event handlers to plugin buttons from a given plugin's handleClick function.

resizeTimer

  • Initial value: -1
  • Comment (in the code): Holds the ID of the timeout used when resizing the window (for clearing)

Used for holding the timeout set before loading when the user resizes the window (resize timeout is set in handleEvents()).

scrollbarWidth

  • Initial value: 0
  • Comment (in the code): Set to the actual scrollbar width in init()

Stores the scrollbar width to be used in viewer pane size calculations.

selector

  • Initial value: ''
  • Comment (in the code): Uses the generated ID prefix to easily select elements

For example, to select an element with ID 1-diva-foo, and given that there is only one document viewer on the page, one would do document.getElementById(settings.selector + 'foo').

See settings.ID.

throbberTimeoutID

  • Initial value: -1
  • Comment (in the code): Holds the ID of the throbber loading timeout

Used to clear the timeout (with clearTimeout()) if the request completes before the timeout ends. See also settings.throbberTimeout.

toolbar

  • Initial value: null
  • Comment (in the code): Holds an object with some toolbar-related functions

Holds functions for updating the toolbar display (see createToolbar()).

verticalOffset

  • Initial value: 0
  • Comment (in the code): See horizontalOffset

See settings.horizontalOffset.

verticalPadding

  • Initial value: 0
  • Comment (in the code): Either the fixed padding or adaptive padding

See settings.fixedPadding and settings.adaptivePadding for details on how this is calculated.

viewport

  • Initial value: null
  • Comment (in the code): Object caching the viewport dimensions
Add a custom footer
Clone this wiki locally