Paver

Replicating the photo viewer/panner seen on the experimental Facebook Pages app

Custom triggers

Paver exposes several public functions that developers can manipulate with in order to trigger desired behavior without interacting with the plugin. In order to maintain direct chainability with other jQuery methods, I have chosen not to implement public methods that can be called by chaining, i.e. $(selector).paver().destroy(). However, I have provisioned three distinct ways where you can access public functions in Paver. args represent accepted arguments for the respective public function(s):

  1. By accessing the plugin_data object of the Paver instances: 
    $(selector).data('plugin_paver').customTrigger([args]);
  2. By passing the name of custom trigger as a string into the .paver() method: 
    $(selector).paver('customTrigger'[, args]);
  3. By triggering a namespaced custom event at the Paver instance: 
    $(selector).trigger('customTrigger.paver');

Note that all custom triggers will only be triggered after the Paver is successfully intialized and ready to use, i.e. when the ready.paver event is fired. To avoid user confusion/frustration when accessing public functions in the event that Paver is not yet ready, I strongly recommend also binding events after ready.paver has been fired, i.e.:

// Initialize paver
$(paverSelector).paver();

// Allow user to destroy instance only after when ready
$(paverSelector).on('ready.paver', funtion() {
	$('button').prop('disable', false);
});
$('button').on('click', function() {
	$(paverSelector).paver('destroy');
	// or: $(this).data('plugin_paver').destroy();
	// or: $(this).trigger('destroy.paver');
});
Function name Arguments Description
destroy None

Destroys the Paver instance, and reinserts the original DOM node in its place. Will emit the destroyed event when completed.
pan Object
{
  xPos: number,
  yPos: number
}

Pans the panorama in the Paver instance. Only a single argument is accepted, and it has to be in the form of an object. xPos refers to the position along the x-axis while yPos refers to the position along the y-axis (implemented, but not used—future support for vertical panoramas). The values of xPos and yPos will be coerced to fall in the range of 0≤n≤1, where n refers to the number passed to each parameter.

When no arguments are passed, triggering pan will pan the panorama to the start position defined in the plugin configuration.
recompute None

Triggers recomputing and binding of events to Paver instances that satisfy the selector. Will emit the recomputeStart event when initiated.

Custom events

There are two kinds of custom events emitted: global custom events, or scoped custom events (triggered by each Paver instance). All events are namespaced, i.e. eventName.paver. The purpose behind creating custom events is to enable developers to (1) check if Paver has been enabled, (2) verify that gyroscopic data is available, (3) keep track of the progress of Paver initialization or the internal calculation events triggered.

Global

Global events are triggered on the document object, i.e:

$(document).on('enabled.paver', function() {
    // Paver is enabled!
});
Event Name Conditional Description
hasGyroscopeData Yes. See also: hasNoGyroscopeData

This event and hasNoGyroscopeData are mutually exclusive. Fired when Paver determines that gyroscopic data is available (alpha, beta and/or gamma is not null.

The following gyroscopic data is passed to the event handler as an object, when the JavaScript deferred object is resolved:

{
    orientation: {
        alpha: <deviceOrientationEvent.alpha>,
        beta: <deviceOrientationEvent.beta>,
        gamma: <deviceOrientationEvent.gamma>
    },
    status: {
        deviceOrientationEventSupport: <boolean>,
        deviceOrientationData: <boolean>
    }
}

The gyroscopic data object can be accessed using:

$(document).on('hasGyroscopeData.paver', function(e, d) {
    // Gyroscopic data available
    console.log(d);
});
hasNoGyroScopeData Yes. See also: hasGyroscopeData

This event and hasGyroscopeData are mutually exclusive. Fired when Paver determines that gyroscopic data is unavailable (alpha, beta and/or gamma is returns null), and/or when the device does not support the deviceorientation event. The following data is passed to the event handler as an object, when the JavaScript deferred object is rejected:

{
    status: {
        deviceOrientationEventSupport: <boolean>,
        deviceOrientationData: <boolean>
    }
}
enabled Yes. See also: disabled

This event and disabled are mutually exclusive. Fired when Paver is conditionally determined to initialize internally, only when the device satisfies the following criteria:

  • does not have a working gyscorope (e.g. most desktops and laptops)—Paver will listen to mousemove events
  • has a gyroscope and is a touch-based device (e.g. some mobile devices and tablets)—Paver will listen to mousemove and deviceorientation events
disabled Yes. See also: enabled

This event and enabled are mutually exclusive. Fired when it is determined that Paver will not be of use:

  • user is on a touch device that has no gyroscope (will fall back to original markup)

Scoped (Individual)

Scoped (individual) events are triggered on the selector for each Paver instance, i.e:

$('div.paver').on('init.paver', function() {
    // Paver is initialized
});

Note that many scoped events are mutually-exclusive, such that only one in a pair will be triggered. They are labelled as "conditional" in the table below:

Event Name Conditional Description
imageLoadDone Yes. See also imageLoadFail

This event and imageLoadFail are mutually exclusive. Fired when the panorama image has been successfully loaded. All computations performed by Paver are only rigged to fire after the panorama image is loaded, so that its natural dimensions are accessible to Paver. This allows Paver to be initialized— see init
imageLoadFail Yes. See also imageLoadDone

This event and imageLoadDone are mutually exclusive. Fired when panorama image has failed to load, and Paver will not be initialized.
init No

Fired when Paver is initialized, i.e. when DOM replacements are performed. This happens after:

  • the class .paver--initialized has been added to the selector, and
  • the title and alt attributes from the image has been read, and inserted into .paver__meta if the option meta or data-meta is set to true.
ready No

Fired when original panorama image is hidden and DOM replacements have been performed. At this point the plugin will proceed to compute dimensions and conditionally bind/unbind events.
computeEnd No

Fired when panorama dimensions have been computed, and the dimensions of the dummy panorama wrapper have been set.
eventsBound Yes. See also: eventsUnbound

This event and eventsUnbound are mutually exclusive. Binding of events relies whether the panorama is really overflowing from its parent container (hence the need for Paver).
eventsUnbound Yes. See also: eventsBound

This event and eventsBound are mutually exclusive. Events will be unbound when the panorama is not wide enough to overflow its parent container (hence no need for Paver).
initialPanStart Yes. See also: panStart

This event and panStart are mutually exclusive. Fired whenPaver is first initialized, which will pan the panorama to a default position (center) or a user-determined position along the x-axis.
panStart Yes. See also: initialPanStart

This event and initialPanStart are mutually exclusive—it is not fired for the first panning event. Fired when the panning of the panorama is initiated. Panning can occur under several conditions:

  • when mousemove is triggered, which will pan the panorama according to the cursor's relative position in the panorama container,
  • when deviceorientation change is triggered, which will pan the panorama according to interpreted tilt along the beta and/or gamma value from the device gyroscope.
initialPanEnd Yes. See also: panEnd

This event and panEnd are mutually exclusive. Fired when Paver is first initialized, which will pan the panorama to a default position (center) or a user-determined position along the x-axis. Listens to the transitionend event (with prefixed support for various browsers).
panEnd Yes. See also: initialPanEnd

This event and initialPanEnd are mutually exclusive— it is not fired after the completion of the first panning event. Fired when the panning of the panorama is complete, listens to the transitionend event (with prefixed support for various browsers).
recomputeStart No

Fired when a window resize event is detected, or a recompute.paver custom trigger is fired. This will force Paver to recompute the dimensions of the panorama and also re-evaluate of events should be bound or unbound.
destroyed No

Fired when the Paver instance has been destroyed—this occurs after the reinsertion of the original DOM node, removal of all event handlers, resetting of Paver-related classes and resetting of the initialization status of the Paver instance of element(s) of interest.