-
Notifications
You must be signed in to change notification settings - Fork 40
Events System
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.
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.
The 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.settings. Within this function, accessing the JavaScript 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.
If the 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.
diva.Events.unsubscribe(handle, completely);
The 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 diva.Events.subscribe.
For example, when subscribing, we could write:
var myHandle = diva.Events.subscribe("ObjectDidLoad", loadMetadata);
Then to unsubscribe from the same event:
diva.Events.unsubscribe(myHandle);
Use the 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:
diva.Events.unsubscribeAll(instanceID)
Calling 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!
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 $('#diva-wrapper').diva.getSettings();.
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.
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.
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.
Fires every time the viewer scrolls. This Event fires a lot, so if you don't want your subscribing function to fire every single time a scroll event occurs, you might want to wrap it in a Javascript setTimeout() call.
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.