-
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 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 self. This parameter will become the JavaScript this in any functions that are subscribed to the specific event; 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 a new page has loaded, and pass the new page index, filename, and selector (stored in the variables pageIndex, filename, and pageSelector respectively) to any subscribers:
diva.Events.publish("PageDidLoad", [pageIndex, filename, pageSelector], self)
diva.Events.subscribe(topic, callback, instanceID)
In our PageDidLoad example, we might want to call a function every time a page has loaded:
diva.Events.subscribe("PageDidLoad", highlight, self)
In the example above, highlight(pageIndex, filename, pageSelector) will be called every time a page loads. This is because the PageDidLoad event publishes [pageIndex, filename, pageSelector]. 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 self variable holds a reference to that instance. Specifying the current Diva instance stored in self 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 PageDidLoad example, this array would look like ["PageDidLoad", highlight]. 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("PageDidLoad", highlight);
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.
(For more detailed code documentation, see Diva's Events system in utils.js on line 668.)
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 the entire document has 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 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 a page has finished loading. Passes the page index, filename, and CSS selector of the <div> element of the page to be loaded. Subject to settings.pageLoadTimeout (Document view) or settings.rowLoadTimeout (Grid view), which wait for an interval to see if the user is scrolling past the current page or not.
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 when 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.
If the highlight plugin is loaded, this event fires when the highlight function has finished highlighting the current page. The highlight function is called every time the current page changes, regardless of whether there is anything to be highlighted on the current page (it is itself subscribed to the PageWillLoad event).
If the canvas plugin is loaded, this event fires when the user closes Canvas view.
If the canvas plugin is loaded, this event fires when the user opens Canvas view.