Scripted Event API

zepheiryan edited this page Sep 26, 2012 · 12 revisions

Events are the best way to hook into Exhibit. Events are based on jQuery, so you should be loading jQuery and assuming it exists when you write code bound to the hooks. Exhibit won't load jQuery if it's already detected in the page.

Caveat

These events are somewhat experimental in nature. This means you should be somewhat wary of committing to the mechanics outlined below and that you should also feel free to suggest ways to make it better.

Locales

All events are triggered on the document element.

registerLocalization.exhibit is triggered when enough of the system has loaded that it can deal with loading locales. Exhibit listens to itself for this, but it is likely a low usage event. This event sends an Exhibit.Registry as its only argument (a static component registry).

registerLocales.exhibit is triggered when the system is ready for locales to be registered (to tell the system they exist, loading is reserved for locales that match the user environment). Locale loading (after registering) must complete before Exhibit can be run. Exhibit listens to itself for this, but it is likely a low usage event.

beforeLocalesRegistered.exhibit is triggered by Exhibit's manifest of locales (locales/manifest.js) before registering any locales. Hooking to this should provide sufficient time to register your own locale. Exhibit does not listen for this at all.

localesRegistered.exhibit is triggered by Exhibit's manifest of locales after all have been registered. Exhibit listens to itself for this to move to the locale selection phase.

localeSet.exhibit is triggered when the most appropriate locale has been chosen, but not loaded. Exhibit listens for this to move into the locale loading phase.

localeLoaded.exhibit is triggered after the scripts defining a locale have been loaded (e.g., all have been fetched from the network). Likely a low usage event. Exhibit listens to itself for this.

Pre-initialization / loading

All events are on the document object.

loadExtensions.exhibit is triggered after localeSet.exhibit` is fired, making extensions aware that the main body of Exhibit has loaded and can be extended safely.

scriptsLoaded.exhibit is triggered after localeLoaded.exhibit is fired, clearing the way to start running Exhibit. Exhibit listens to itself for this.

registerStaticComponents.exhibit is triggered to register importers, exporters, and localization (so far) with the system. Any type of component that does not receive user interaction and essentially does not change regardless of data or browsing session can be loaded as a static component. This event sends an Exhibit.Registry as its only argument. Exhibit listens to itself for this to start registering static components.

staticComponentsRegistered.exhibit is triggered after the above event is triggered under the assumption that all static components will have finished their registration quickly. This may not be a correct assumption and should possibly be explored further; however, it is currently the case that all Exhibit core registrations are doing no more than informing the registry of their existence. Exhibit listens to itself for this to start creating an exhibit.

registerExporters.exhibit is triggered during component registration to register exporters. Add an exporter by listening for this event on document. Exhibit listens to itself for this when registering its own native exporters.

registerImporters.exhibit is triggered during component registration to register importers. Add an importer by listening for this event on document. Exhibit listens to itself for this when registering its own native exporters.

registerJSONPImporters.exhibit is triggered during importer registration to register JSONP importers dependent on the JSONP importing framework having loaded before they can be defined. Exhibit listens to itself for this when registering its own native JSONP importers.

delayCreation.exhibit should be triggered by an extension that loads third-party scripts. Exhibit listens for this and delays triggering scriptsLoaded.exhibit until all delays have been resolved. The triggering code should provide a delay identifier; this can be generated by calling Exhibit.generateDelayID(). A delayCreation signal should be paired to a delayFinished signal, below. Example:

var delayID = Exhibit.generateDelayID();
$(document).trigger("delayCreation.exhibit", delayID);

delayFinished.exhibit should be triggered after the third-party scripts have finished loading. Exhibit listens for this in order to continue with its initialization process. The triggering code should send the same delay identifier along as was used for the delay creation.

Initialization

All events are on the document object.

registerComponents.exhibit is triggered to register dynamic components that rely on the configuration, data, and browsing and possibly need to have state tracked in the history system. This event sends an Exhibit.Registry as its only argument. Exhibit listens to itself for this event in several places, like facets, views, etc.

registerFacets.exhibit is triggered to register facet types.

dataload.exhibit is triggered after the database has been populated with linked data sources but before Exhibit begins to create an instance of itself. This takes the place of the ex:ondataload attribute on the body, the semantics of which were to completely replace instance creation when autoCreate was enabled. Instead, listening for and triggering off this event will run code in conjunction with instance creation. Exhibit listens to itself for this event to begin instance creation.

exhibitConfigured.exhibit is triggered when the Exhibit instance configuration (usually from DOM) is done. This event sends an Exhibit._Impl as its only argument. Exhibit listens to itself to start initializing the bookmark and history systems.

View Panel

All events are on the element associated with the view panel, retrieved with viewPanel.getContainer().

onBeforeViewPanelSwitch.exhibit Fires before the view changes from the current view to the next view, supplying the index of the current view as an event argument. Because the current view and its contents will almost immediately be destroyed after this event is signalled, it is not supplied as an argument.

onAfterViewPanelSwitch.exhibit Fires after the view changes from the previous view to the current view, supplying the index of the new view and the new view as event arguments.

Views

All events are triggered on the document.

onItemShow.exhibit is triggered right before an item is displayed in any view. This duplicates the functionality of the ex:onshow attribute in a lens. The item identifier and the node (as a DOM element) are passed as arguments of the event.

Collection

All events are triggered on the collection, found through an element's UI Context: uiContext.getCollection().getElement().

onResetAllFilters.exhibit is triggered when the clear all filters link is clicked.

Facets

All events are on the element associated with the facet, retrieved with facet.getContainer(). Note not all facets follow this model, e.g., the Text Search Facet has no notion of a facet value being selected.

onBeforeFacetReset.exhibit is triggered before a facet's restrictions are wiped clean, supplying an array of the current restrictions as arguments.

Text Search Facet

onTextSearchFacetSearch.exhibit Fires before the facet takes the text in its input and does a search on it, supplying the string to search on as an argument.

UI / Dialogs

All events are on the document object.

All of the events in this section are experimental and may need further development to work well.

error.exhibit is used to display errors. Caught exceptions should fire this event signal in order to display to the user in the page that an error requiring their attention has occurred. The exception object and an explanatory message are two arguments that should be supplied when this event is signaled.

modelessCreated.exhibit is triggered on the element by a child dialog whenever a modeless dialog is opened in the UI. Exhibit listens to itself for this to register parent-child dialog relationships.

modalSuperseded.exhibit is triggered on the document whenever a modal dialog is opened in the UI, taking the focus from any other modal dialog. Exhibit listens to itself for this to remove focus.

cancelModeless.exhibit is triggered when a document.body click is recorded and found to not be within the bounds of a modeless dialog, which will close that dialog. Handlers bound to this event should unbind themselves as they conclude their handling phase. Clicks within the dialog descendant of another modeless dialog will not close the parent dialog.

cancelModal.exhibit is triggered when a modal dialog is intentionally closed. Exhibit listens to itself for this to move any earlier modal dialog to the top of the focus.

cancelAllModeless.exhibit is triggered on document to close all modeless dialogs. Exhibit listens to itself for this to close all modeless dialogs.

A modal dialog will bind a handler to all clicks on the document.body to prevent their firing anything on any other element, unbinding when the dialog is closed.

Collections

All events are triggered on an Exhibit.Collection's associated element, retrieved with collection.getElement().

onItemsChanged.exhibit is fired when a facet is added, a facet is removed, or a facet is updated. Other facets should listen to the collection for this event in order to incorporate any changes in the set of restricted items.

onRootItemsChanged.exhibit is fired when the data underlying a collection is modified. Facets should listen to the collection for this event in order to dispose of any cached material based on the state of the database prior to the change.

History

importReady.exhibit is sent by a component when it can take in the current history's state for itself. The History utility will tell each component what to import when a state change is triggered, but not every component is immediately ready. Exhibit listens to itself for this, especially in views.

Database

All events are triggered on the document object.

onBeforeLoadingTypes.exhibit Paired with the next event signal, fires before and after the database processes type schema information.

onAfterLoadingTypes.exhibit

onBeforeLoadingProperties.exhibit Paired with the next event signal, fires before and after the database processes property schema information.

onAfterLoadingProperties.exhibit

onBeforeLoadingItems.exhibit Paired with the next event signal, fires before and after the database processes the items going into the database.

onAfterLoadingItems.exhibit

onBeforeRemovingAllStatements.exhibit Paried with the next event signal, fires before and after the database is wiped clean.

onAfterRemovingAllStatements.exhibit

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.