Skip to content

Public Methods

Jump to bottom Edit New page
Eric Han Liu edited this page Sep 24, 2018 · 41 revisions

Public methods can be called from anywhere on an instance of Diva.

An easy way to grab an instance of Diva is to make the diva variable global when creating it in the HTML (by removing the let statement), then the diva object will exist for interaction.

diva = new Diva('diva-wrapper', {
    objectData: "manifest.json"
});

You can then call methods like so:

diva.gotoPageByIndex(150);

See below for a complete list of public methods.

Contents

activate

Registers this Diva instance as the 'active' Diva object -- i.e. if there are multiple Diva viewers on the same page, this one will receive focus with regards to keystrokes for scrolling.

Parameters: none
Returns: none

changeObject

Allows for changing the document the user is viewing without having to destroy and reload the viewer instance. Simply pass it the new URL (i.e. to a IIIF manifest) and the viewer clears the current document and loads the data from the new manifest.

Parameters: {String} objectData - The new objectData setting
Returns: none

changeView

Switches the document viewer to the specified view.

Parameters: {String} destinationView - 'document', 'book', or 'grid'
Returns: none

deactivate

De-registers this Diva instance as the 'active' Diva object. It will no longer listen to keystrokes for scrolling and other non-browser-default user input.

Parameters: none
Returns: none

destroy

Destroys this instance, and tells plugins to clear any data (via each plugin's destroy method). Also clears all events in the Events System.

Parameters: none
Returns: none

disableScrollable

Disables document dragging, scrolling (by keyboard if set with enableKeyScroll), and zooming by double-clicking.

Parameters: none
Returns: none

enableScrollable

Re-enables document dragging, scrolling (by keyboard if set with enableKeyScroll), and zooming by double-clicking.

Parameters: none
Returns: none

disableDragScrollable

Disables document drag scrolling.

Parameters: none
Returns: none

enableDragScrollable

Re-enables document drag scrolling.

Parameters: none
Returns: none

enterFullscreenMode

Enter fullscreen mode if currently not in fullscreen mode. This function will work even if enableFullscreen is set to false.

Parameters: none
Returns: False if in fullscreen mode initially, true otherwise.

enterGridView

Enter grid view if currently not in grid view.

Parameters: none
Returns: True if not in grid view initially, False otherwise.

getActivePageIndex

Get the page index of the current active page (with indexing starting at 0). Active refers to page whose boundaries are most visible.

Parameters: none
Returns: An integer representing the current active page number, 0-indexed.

getAllPageURIs

Gets all the page image URIs in the IIIF manifest.

Parameters: none
Returns: An array of all the URIs in the document

getCurrentCanvas

Gets the canvas identifier for the currently visible page.

Parameters: none
Returns: The URI of the currently visible page's canvas

getCurrentPageDimensionsAtCurrentZoomLevel

Get the dimensions of the current page at the current zoom level. Note that this works in any view, including grid view.

Parameters: none
Returns: An object of format { width: w, height: h }.

getCurrentPageFilename

Get the filename of the current page. Will be deprecated in the next version of Diva, use getCurrentPageURI instead.

Parameters: none
Returns: A string containing the current page's filename.

getCurrentPageIndices

Get the page indices of the current (visible) pages (with indexing starting at 0).

Parameters: none
Returns: An array of integers representing the current visible page numbers, 0-indexed.

getCurrentPageOffset

Shortcut for getPageOffset for the current page.

Parameters: none
Returns: An object with two parameters (top, left) representing the offset. Similar to jQuery's $(selector).offset().

getCurrentPageURI

Gets the URI for the current page.

Parameters: none
Returns: The URI for the current page image.

getCurrentURL

Gets the URL to the current state of the document viewer. This url includes hash parameters at the end of the URL that represent the viewer state. See getState for an enumeration of these properties.

Parameters: none
Returns: A string containing the current page's full URL with viewer parameters.

getFilenames

Get an array of all filenames in the document. Will be deprecated in the next version of Diva, use getAllPageURIs instead.

Parameters: none
Returns: An array of strings representing each page's filename.

getGridPagesPerRow

Get the number of grid pages per row in grid mode.

Parameters: none
Returns: An integer representing the number of grid pages per row.

getInstanceId

Gets the instance ID -- essentially the selector without the leading '#' (i.e. "diva-1-"). (See getInstanceSelector).

Parameters: none
Returns: A string representing the instance ID.

getInstanceSelector

Gets a string representing the CSS ID prefix for a the elements belonging to a document viewer instance. For example, if the viewer's ID is 1, the instance selector is "#diva-1-".

Parameters: none
Returns: A string representing the instance selector.

getItemTitle

Returns the title of the document, based on the label in the IIIF manifest.

Parameters: none
Returns: A string representing the title of the document.

getMaxZoomLevel

Gets the maximum zoom level for the entire document.

Parameters: none
Returns: An integer representing the maximum zoom level.

getMaxZoomLevelForPage

Gets the maximum zoom level for a given page.

Parameters: {int} pageIndex - The index of the desired page
Returns: An integer representing the maximum zoom level for the given page.

getMinZoomLevel

Gets the minimum possible zoom level (checks for validity first).

Parameters: none
Returns: An integer representing the minimum zoom level.

getNumberOfPages

Gets the total number of pages in the document.

Parameters: none
Returns: False if the document view has not completed loading, otherwise an integer representing the number of pages.

getOtherImages

If a canvas has multiple images defined, gets the non-primary images.

Parameters: {int} pageIndex - The page index for which to return the other images. Returns: An array containing the other images (objects).

getPageDimensions

Gets the page dimensions in the current view and zoom level.

Parameters: {int} pageIndex - The 0-based page index.
Returns: An object of format { width: w, height: h }.

getPageDimensionsAtCurrentZoomLevel

Same as getPageDimensions, but also works in grid view.

Parameters: {int} pageIndex - The 0-based page index.
Returns: An object of the form { width: w, height: h }.

getPageDimensionsAtZoomLevel

Gets the dimensions of a given page index at a given zoom level. If you want the dimensions for the current page, see getCurrentPageDimensionsAtCurrentZoomLevel. If the zoom level given is higher than maximum, returns the page dimensions at the maximum zoom level.

Parameters:

  • {int} pageIndex - The 0-based page index.
  • {int} zoomLevel - The zoom level for the desired page dimensions.

Returns: An object of format { width: w, height: h }.

getPageImageURL

Gets the URL for the image of the page at the given index. The optional size parameter supports setting the image width or height (default is full-sized).

Parameters:

  • {string} pageIndex - The filename of the page whose index is to be retrieved.
  • {object} size - An object of format { width: w, height: h }.

Returns: A string of the IIIF URL for the desired page at the optional size.

getPageIndexForPageXYValues

Get the page index corresponding to a given set of page x/y values

Parameters:

  • {int} pageX - pageX value of (x, y) point to check
  • {int} pageY - pageY value of (x, y) point to check

Returns: An integer representing the 0-based page index of the diva page-element that exists at the point (x, y), -1 if not found.

getPageOffset

Get the distance between the top-left corner of diva-inner and the top-left corner of the queried page.

Parameters: {int} pageIndex - The 0-based page index.
Returns: An object of format { top: t, left: l } representing the offset. Similar to jQuery's $(selector).offset().

getSettings

Gets on object representing the current values of each setting for this instance of the document viewer. For documentation on these settings, see Settings. Note that this object is read-only.

Parameters: none
Returns: An object representing all settings of the document viewer instance.

getState

Get an object representing the state of this diva instance. This object can be supplied as an argument to setState().

The object format is as follows:

{
    'f': settings.inFullscreen,    // A boolean representing whether the viewer is in fullscreen
    'v': string                    // A string representing whether the viewer is in 'd' document, 'b' book, or 'g' grid view
    'z': settings.zoomLevel,       // An int representing the current zoom level
    'n': settings.pagesPerRow,     // An int representing the current number of pages per row in grid view
    'i': string                    // The filename of the current page, if settings.enableFilename is true. Else, false.
    'p': settings.currentPageIndex // An int representing the current page index if settings.enableFilename is false. Else, false.
    'y': int                       // If in document view, the Y offset from the center of the current page.
    'x': int                       // If in document view, the X offset from the center of the current page.
}

Parameters: none
Returns: An object (as shown above) representing the viewer state.

getZoomLevel

Gets the current zoom level.

Parameters: none
Returns: An integer representing the current zoom level.

gotoPageByIndex

Jumps to a particular page (0-indexed).

Parameters:

  • {int} pageIndex - The index of the page to jump to.
  • {string} xAnchor - Optional. The horizontal anchor for the desired page. May be either 'left', 'right', or (default if not provided) 'center'.
  • {string} yAnchor - Optional. The vertical anchor for the desired page. May be either 'top', 'bottom', or (default if not provided) 'center'.

Returns: True if the page index represents a valid page, false otherwise.

gotoPageByLabel

Given a canvas label, will attempt to go to that page. If no label was found, the label will be attempted to match against the page index.

Parameters:

  • {string} label - The label to search on.
  • {string} xAnchor - Optional. The horizontal anchor for the desired page. May be either 'left', 'right', or (default if not provided) 'center'.
  • {string} yAnchor - Optional. The vertical anchor for the desired page. May be either 'top', 'bottom', or (default if not provided) 'center'.

Returns: True if successful, false if the label cannot be found and cannot be matched against an index.

gotoPageByName

Jumps to a page based on its filename. Will be deprecated in the next version of Diva, use gotoPageByURI instead.

Parameters:

  • {string} filename - The filename of the image to jump to.
  • {string} xAnchor - Optional. The horizontal anchor for the desired page. May be either 'left', 'right', or (default if not provided) 'center'.
  • {string} yAnchor - Optional. The vertical anchor for the desired page. May be either 'top', 'bottom', or (default if not provided) 'center'.

Returns: True if successful, false if the filename cannot be found.

gotoPageByURI

Jumps to a page based on its URI.

Parameters:

  • {string} URI - The URI of the image to jump to.
  • {string} xAnchor - Optional. The horizontal anchor for the desired page. May be either 'left', 'right', or (default if not provided) 'center'.
  • {string} yAnchor - Optional. The vertical anchor for the desired page. May be either 'top', 'bottom', or (default if not provided) 'center'.

Returns: True if successful, false if the URI cannot be found.

hasOtherImages

Whether the page canvas has other images to display.

Parameters: {int} pageIndex - The 0-based page index.
Returns: True if the page has other images to display, false otherwise.

hideNonPagedPages

If the IIIF manifest contains pages tagged as 'non-paged' in the 'viewing-hints', they will be hidden.

Parameters: none
Returns: none

isInFullscreen

Checks if the viewer is currently in fullscreen mode.

Parameters: none
Returns: True if the viewer is in fullscreen mode, false if not.

isPageIndexValid

Checks if a page index is within the range of the document.

Parameters: {int} pageIndex - The 0-based page index.
Returns: True if the page index is valid, false if not.

isPageInViewport

Determines if a page is currently in the viewport.

Parameters: {int} pageIndex - The 0-based page index.
Returns: True if any part of the page is currently in the viewport, false otherwise.

isReady

Checks whether the viewer is fully loaded and ready to use.

Parameters: none
Returns: True if the viewer has completed loading, false otherwise.

isRegionInViewport

Checks if any part of something (e.g. a highlight box on a particular page) is visible (i.e. its top, left, middle, right, or bottom falls within the current viewport).

Parameters:

  • {int} pageIndex - The page index the element is on (0-indexed).
  • {int} leftOffset - The x-offset of an element.
  • {int} topOffset - The y-offset of an element.
  • {int} width - The width of an element.
  • {int} height - The height of an element.

Returns: True if the element is in the viewport, false otherwise.

isVerticallyOriented

Reports whether the viewer is in vertical orientation or horizontal orientation.

Parameters: none
Returns: True if the viewer is in vertical orientation, false if horizontal.

leaveFullscreenMode

Leave fullscreen mode if currently in fullscreen mode.

Parameters: none
Returns: True if viewer was in fullscreen mode when called, false otherwise.

leaveGridView

Leave Grid view.

Parameters: none
Returns: Returns true if the viewer was in Grid view when called, false otherwise.

setGridPagesPerRow

Set the number of grid pages per row.

Parameters: {int} pagesPerRow - The number of pages per row in grid view.
Returns: True if the operation was successful, false otherwise.

setState

Align this Diva instance with a state object (as returned by getState()).

Parameters: {object} state - See getState() for object format.
Returns: True if the operation was successful.

setZoomLevel

Set the zoom level of the document viewer.

Parameters: {int} zoomLevel - The zoom level to set.
Returns: True if the operation was successful, false otherwise.

showNonPagedPages

If the IIIF manifest contains pages tagged as 'non-paged' in the 'viewing-hints', they will be shown.

Parameters: none
Returns: none

toggleFullscreenMode

Toggles the viewer into and out of fullscreen mode.

Parameters: none
Returns: none

toggleNonPagedPagesVisibility

Toggles the visibility of pages tagged as 'non-paged' in IIIF manifests.

Parameters: none
Returns: none

toggleOrientation

Switches between vertical orientation and horizontal orientation.

Parameters: none
Returns: true if document is now vertically oriented, false if now horizontal.

translateFromMaxZoomLevel

Translates a measurement from the zoom level on the largest size to one on the current zoom level.

For example, a point 1000 on an image that is on zoom level 2 of 5 translates to a position of 111.111... (1000 / (5 - 2)^2).

Works for a single pixel co-ordinate or a dimension (e.g., translates a box that is 1000 pixels wide on the original to one that is 111.111 pixels wide on the current zoom level).

Parameters: {int} position - The measurement to be translated from the maximum to the current zoom level.
Returns: An integer representing the translated measurement.

translateToMaxZoomLevel

Translates a measurement from the current zoom level to the position on the largest zoom level.

Works for a single pixel co-ordinate or a dimension (e.g., translates a box that is 111.111 pixels wide on the current image to one that is 1000 pixels wide on the current zoom level).

Parameters: {int} position - The measurement to be translated from the current to the maximum zoom level.
Returns: An integer representing the translated measurement.

zoomIn

Zooms the document viewer in by one zoom level. If in Grid view, switches to Document view.

Parameters: none
Returns: False if the viewer is already at the maximum zoom level, otherwise true.

zoomOut

Zooms the document viewer out by one zoom level. If in Grid view, switches to Document view.

Parameters: none
Returns: False if the viewer is already at the minimum zoom level, otherwise true.

Add a custom footer
Clone this wiki locally