Examples

You can try Birdview on various pages from this website:

Usage

1. Setup

Include birdview.js and birdview.css in your HTML file: 

<link rel="stylesheet" type="text/css" href="birdview.css"/>
<script type="text/javascript" src="birdview.js"></script>

2. Start

Enable Birdview by calling the initialization method: 

birdview.init();

3. Control

You can trigger Birdview by pressing the Z key or with a pinch-in gesture on a touch device.

You can also trigger Birdview by clicking any HTML element with a birdview_toggle class: 

<button class="birdview_toggle">Birdview</button>

Or you can toggle Birdview programmatically using the toggle method: 

birdview.toggle();

4. Stop

You can stop Birdview from running on your page by calling: 

birdview.destroy();

The destruction method is called inside the initialization method. Calling birdview.init() multiple times shouldn't create any undesirable overlapping.

Options

You can modify Birdview's default settings by passing a configuration object to the initialization method: 

birdview.init({
    shortcut: 90,
    button: true,
    button_text: 'Birdview',
    speed: 0.3,
    easing: 'ease',
    overlay: true,
    origin_X: 50,
    callback_start: function(){},
    callback_end: function(){}
});

1. User interface

2. Effects

3. Callbacks

Here's how you can use callback functions: 

function fly(){
    console.log('taking off');
}

function land(){
    console.log('landing');
}

birdview.init({
    callback_start: fly,
    callback_end: land
});

Example: when you are in Birdview, you can emphasize your headings while fading out everything else.

How it works

Birdview.js wraps all body HTML content inside a custom DOM structure: everything is put inside an inner div birdview_child, itself wrapped inside an outer div birdview_parent: 

<body>
    <div id="birdview_parent">
        <div id="birdview_child">
            <!-- Original HTML -->
        </div>
    </div>
</body>

The birdview effect is performed using CSS scale transforms on the birdview_child div. To ensure a continuous transition between the current scrolling position and the birdview, the Y origin of the scale transform must be at the vertical midpoint of the viewport.

The vertical midpoint of the viewport is then projected into the document, and a CSS scale transform is applied to the birdview_child using the projected origin. But if we stop there, the birdview wouldn't necessarily fit inside the viewport: some of the scaled document would be hidden below or above the viewport, depending on your scrolling position, precisely because the vertical midpoint of the viewport isn't necessarily the vertical midpoint of the document—with the notable exception of when you are exactly halfway through the document!

To compensate for that shift, we must apply a vertical translation that is dependent on your scrolling position. That translation is applied to the birdview_parent div.

Finally, user interface elements such as the optional overlay and button are appended directly to the body, outside the birdview_parent, so they are not subject to transformations.

This DOM structure has one consequence for the developer: if your own code creates HTML elements programmatically and appends them to the body element, then the call order of birdview.init() matters. If you wish to not include programmatic HTML elements in the birdview, please execute your code after you initialize birdview.js.

Change log

Known issues

Birdview.js is tested on:

License

Birdview.js is published under the GNU General Public License.