Paver

Introduction

Paver was initially a simple personal project to make panoramas more accessible. After upgrading from an iPhone 4 to a spanking new 6, I unlocked the world of panoramas made by a single, steady wave of the hand. Panoramas are breathtakingly beautiful when used correctly, but I have always been frustrated with how the default screens, in aspect ratios that are largely incompatible with the ultrawide format of panoramas, don't do these work much justice.

Current status:
Travis CI Build Latest stable Github release

The conundrum

There is indeed an extremely lightweight way of displaying panoramas on a page—you simply wrap it within a container which allows content to oveflow along the x-axis. The markup is straightfoward:

<div class="panorama">
    <img src="/path/to/image" alt="" title="" />
</div>

…and the CSS (in SASS/SCSS flavour) would look something like this:

.panorama {
	height: 400px;
	overflow-x: scroll;
	overflow-y: hidden;
	img {
		height: 100%;
	}
}
We stood at the precipice of the sandy cliffs, in awe of the beautiful setting sun.
Sunset at Nørre Lyngby, Nordjylland We stood at the precipice of the sandy cliffs, in awe of the beautiful setting sun.

Looks good! However, it requires user to drag the scrollbar in order to pan around the panorama. What if we can exploit mouse movement, and even device orientation/rotation, to enhance the user experience of panorama viewing? That is why Paver was developed. And here is the same panorama, with Paver enabled, working on the exact same markup as the panorama above:

We stood at the precipice of the sandy cliffs, in awe of the beautiful setting sun.
Sunset at Nørre Lyngby, Nordjylland We stood at the precipice of the sandy cliffs, in awe of the beautiful setting sun.

How does it work?

There are two parts to how Paver works—firstly, it converts a simple markup, which is essentially an image wrapped in a division element, into something that the plugin can further work with. When that is done, it uses JS to listen to several events that will indicate how the user would want the panorama viewport be positioned.

Markup replacement

Paver works by replacing your markup, which would look something like this:

<div>
    <img src="/path/to/image" alt="" title="" />
</div>

…into…

<div class="paver--init paver--ready">
    <!-- Panorama metadata -->
    <div class="paver__meta">
        <span class="paver__title">Title</span>
        <span class="paver__desc">Description</span>
    </div>

    <!-- Panorama as background image -->
    <div class="paver__pano"></div>

    <!-- Panorama scroller -->
    <div class="paver__scroller">
        <span></span>
    </div>
</div>

Usage

Dependencies

Paver requires jQuery v1.7+, as well as Ben Alman's jQuery Throttle/Debounce plugin. For jQuery, you can use the one hosted by Google API, or the stable releases hosted by jQuery CDN—Paver has been thoroughly tested with jQuery v1.7+, v2+, and v3.1+. For the throttle/debounce plugin, you can use the one available via cdnjs.

Remember, for Paver to work, you will have to load both the plugin's JS file (paver.js or paver.min.js, after the dependencies) and the accompanying stylesheet (paver.css).

Basic usage

For the HTML structure, refer to the minimal basic markup. To initialize Paver, simply chain the .paver() method to your selector of choice. With reference to the minimal basic markup, this would be:

$(function () {
    // Paver
    $('div.panorama').paver();
});

As per standard jQuery plugins, .paver() will return the original object, allowing for further chaining if desired. For configuration options, please refer to configuration options.

Demo

A simple demo of how Paver works. You can resize the viewport to your liking, and Paver will automatically recalculate and recompute all necessary bits and pieces that make it work. The following panorama follows the suggested markup as specified above, but nested within a <figure> element to give context to the caption:

<figure>
    <div data-paver>
        <img src="./images/p1.jpg" title="Sunset in the heart of Aarhus" alt="A panorama taken from the roof of my penthouse unit in the center of Aarhus." />
    </div>
    <figcaption>Sunset in the heart of Aarhus&mdash;A panorama taken from the roof of my penthouse unit in the center of Aarhus.</figcaption>
</figure>
$(function () {
    // Paver
    $('div[data-paver]').paver();
});
A panorama taken from the roof of my penthouse unit in the heart of Aarhus.
The Aarhusian Sunset A panorama taken from the roof of my penthouse unit in the heart of Aarhus.

Features

A Sunday morning walk to the rooftop of Godsbanen, Aarhus.
Godsbanen A Sunday morning walk to the rooftop of Godsbanen, Aarhus.

The panorama above has a smaller aspect ratio than normal: Paver only kicks in when the viewport is narrow enough—so, resize away and see what happens.

Further Information

Usage notes & plugin configuration

For detailed usage notes, please refer to the Usage Notes page. Plugin configuration options are also available in the page.

Advanced usage

For examples of advanced usage, please refer to the Advanced Usage page.

Custom triggers & events

Paver supports custom triggers, which allows developers to force recomputation in the event of user-interaction that is not predicted, due to its non-exhaustiveness and limitless possibilities, by the plugin. In addition, Paver will also fire custom events to allow developers to track the initialization progress of the plugin. Please refer to Custom Triggers & Events for more information.