Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Diva has a publish/subscribe Events system that allows plugins or external applications to hook in at certain points in the document viewing process.
If you are writing your own plugins, you will likely want to subscribe to Events to fire functions in your plugin at the appropriate points, and publish Events to allow Diva and other plugins/applications to react to changes made by your plugin.
Using the Events System
diva.Events.publish(topic, args, scope)
Any arguments (
args) you supply will be passed to subscribers of the event. Arguments must be passed in as an array.
scope argument is optional, but when publishing an event from the main Diva instance should be
this. This allows the events to have access to the public Diva functions and settings. Supplying the
scope argument also allows events to trigger only subscribers subscribed within the same Diva instance, which is useful if there are multiple Diva instances on the same page.
For example, we might want to create an Event for when the manifest object as been setup, and pass the ViewerCore
settings to any subscribers:
// in the ViewerCore class diva.Events.publish("ObjectDidLoad", this.settings, this);
diva.Events.subscribe(topic, callback, instanceID)
In our ObjectDidLoad example, we might want to call a function when the manifest object has been loaded, such as for plugins that depend on an existing manifest object (see Metadata Plugin):
// in the MetadataPlugin class diva.Events.subscribe("ObjectDidLoad", loadMetadata, this.core.settings.ID);
In the example above,
loadMetadata(settings) will be called when the manifest loads, where
settings belongs to the ViewerCore instance. This is because the ObjectDidLoad event in the ViewerCore class publishes
this will give access to all public methods and settings in the Diva object that published the event.
When inside of a Diva instance, the
this variable holds a reference to that instance. Specifying the current Diva instance stored in
this as the
instanceID argument tells the events system to only trigger the subscribed function when
publish is called within the instance with the same ID. This way, if there are multiple Diva instances on the same page,
publish calls within one instance will not affect events in other instances.
instanceID argument is omitted, the subscribed function will be fired regardless of where the event originates on the webpage.
For a list of default events, when they occur, and the data they publish to subscribers, see Core Events.
diva.Events.subscribe returns a
handle that we can use when unsubscribing from the Event.
Unsubscribe and Event Handlers
handle argument is an array of the form
[topic, callback(, instanceID)]. In our ObjectDidLoad example, this array would look like
["ObjectDidLoad", loadMetadata]. We can pass the handle in manually, or we can use the handle returned by
For example, when subscribing, we could write:
var myHandle = diva.Events.subscribe("ObjectDidLoad", loadMetadata);
Then to unsubscribe from the same event:
completely boolean parameter with caution - setting this to
true will unsubscribe all subscribers from the given event, including the default events included in the Diva core. When
completely is set to true, it will unsubscribe all subscribers for an event from the scope of the original
subscribe call if you are using the handle it returned - so if
subscribe was called with the
instanceID parameter, it will only unsubscribe subscribers from that particular instance. If no instance ID was supplied,
unsubscribe will wipe out subscribers to that event globally.
Finally, it is possible to call
unsubscribeAll without any handler:
unsubscribeAll without any ID argument removes all subscribers from all events on the webpage. Supplying it with an
instanceID string that represents a particular Diva instance will unsubscribe all events within the scope of that instance. Instead of an ID,
'global' may be supplied, which unsubscribes all events not subscribed to a particular instance.
These are the Events that Diva publishes so far. The arguments in brackets are passed to subscribed functions.
Subscribe to these in your plugin, and/or fork
diva.js/develop and add more!
DocumentDidLoad [firstPageIndex, fileName]
Fires when Document or Book views have finished loading. Passes the page index and filename of the first page to subscribing functions.
Fires when the document viewer has finished loading. Passes the entire settings object to subscribed functions. Note that the settings object is also available from the diva instance by calling
Fires when the IIIF manifest has been retrieved. Passes the manifest in JSON format to subscribed functions. Note that this event only fires when a IIIF manifest has loaded. Any other type of manifest does not trigger this event.
PageWillLoad [pageIndex, filename, pageSelector]
Fires when Diva starts preparing the next page to load.
As the next page is entering the Document Viewer Pane, Diva loads the necessary structures to display the page before loading the page itself. This event fires when a page container (a
div in HTML) enters the DOM.
Passes the page index, filename, and CSS selector of the
<div> element of the page to be loaded.
Fires when Diva switches in and out of fullscreen mode. Passes a boolean that is true if the viewer is entering fullscreen mode, and false if exiting fullscreen mode.
Fires when Diva switches in and out of Grid view. Passes a boolean that is true if the viewer is entering Grid view, and false if exiting Grid view.
VisiblePageDidChange [pageIndex, filename]
Fires when the page considered "visible" by Diva changes. The visible page is that which takes up most of the document viewer. For example, if the user is scrolled to page 9 and it fills up 1/4 of the viewport, and page 10 fills up 3/4 of the viewport, page 10 is the visible page. This event passes the visible page and its filename to subscribed functions.
Fires when the viewer has zoomed in or out. Passes the new zoom level to subscribers.
Fires when the viewer has zoomed in. Passes the new zoom level to subscribers.
Fires when the viewer has zoomed out. Passes the new zoom level to subscribers.
Fires when the grid row number changes. Passes the new row number to subscribers.
Passes the current scroll position in pixels (measured from the top of the document) to subscribers.
Fires when the viewer has been scrolled up. Passes the current scroll position in pixels (measured from the top of the document) to subscribers.
Fires when the viewer has been scrolled down. Passes the current scroll position in pixels (measured from the top of the document) to subscribers.
Fires when the "Go to Page" box has been used. Passes the index of the requested page to subscribers.
Is up to the user to fire when the panel width/height changes on something that is not a full-window resize. Will automatically call updatePanelSize to update internal variables.
Fires at the start of the 'destroy' process after the
destroy() method is called on a Diva instance. Passes the settings object to subscribers. Should be used to clean up and remove any data associated with the Diva instance.
Fires at the very end of the 'destroy' process after the
destroy() method is called on a Diva instance. Passes the settings object to subscribers.