Events System

Diva has a simple publish/subscribe Events system that allows plugins 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.

Using the Events System

Publish

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. Using the scope argument, you may supply an Object (for example, the default this) within which the Event can be subscribed to.

For example, we might want to create an Event for when a new Article is added, and pass the new article to any subscribers:

Events.publish("ArticleAdded", [article])

Subscribe

Events.subscribe(topic, callback)

In our Article example, we might want to call a function every time an article is added:

Events.subscribe("ArticleAdded", Articles.validate)

If the article was supplied in the args array, it will be passed to the Articles.validate function.

This method returns a handle that we use when unsubscribing from the Event.

Unsubscribe and Event Handlers

Events.unsubscribe(handle, completely)

The handle argument is an array of the form [topic, callback]. In our ArticleAdded example, this array would look like ["ArticleAdded", Articles.validate]. We can pass the handle in manually, or we can use the handle returned by Events.subscribe.

For example, when subscribing, we could write:

var myHandle = Events.subscribe("ArticleAdded", Articles.validate)

Then to unsubscribe from the same event:

Events.unsubscribe(myHandle)

(For further reference, the core of Diva's Events subsystem is located in utils.js on line 710.)

Core Events

Here find a comprehensive list of Events that Diva publishes so far. Subscribe to these in your plugin, and/or fork diva.js/develop and add more!

VisiblePageDidChange
DocumentHasFinishedLoading
ViewerHasFinishedLoading
ModeDidSwitch
ModeHasChanged
VisiblePageDidChange
ViewDidSwitch
ZoomLevelDidChange
GridRowNumberDidChange
PageHasLoaded

plugins/highlight.js

HighlightCompleted

plugins/canvas.js

CanvasViewDidHide
CanvasViewDidActivate