jQuery.Viewport

Very helpfull and lightweight jQuery plugin that makes an element as a handy viewport for displaying elements with absolute position. The plugin is hosted on . You can see it in action right there:

There are two additional plugins are used in this example: jquery.draggable (for dragging) from the jQuery UI library and my another fancy-pancy plugin named (for scrolling).

Code example

CSS

#element {
    height:600px;
    width:350px;
}

HTML

$(function() {
    var element = $('#element').viewport();
    var content = element.viewport('content');

    content.draggable({containment: 'parent'});
    content.scraggable({containment: 'parent'});
});

Downloads (0.2.1)

The production version is minified by Google Closure Compiler with simple optimization mode. To download a file just right-click and use "Save As...".

(minified) - 2.5 kb
- 6.5 kb

Documentation

The plugin creates two frames to display content: the "content" frame and the "binder" frame. They are aligned to the center of the main "viewport" frame. If the content you want to display in a viewport is bigger then the viewport itself then the "binder" frame's size is set by formula - viewport_width + (content_width - viewport_width) * 2 (the same for height). This is the easiest way I've found to prevent "content" frame's borders do not go into the viewport's rect. I can easily say that "content" frame is "draggable" and its "containment" is "parent" and it won't be able to be dragged out the "binder" frame and so its borders will be in the "viewort" frame's rect never.

Binder frame

Content frame

Viewport frame

If the content you want to display is smaller then "viewport" frame then the "binder" frame's size wil be the same as "content" frame's size and they will always be aligned to the center of the "viewport" frame.

Viewport frame

Binder frame Content frame

Options

content Default: false

Reference or selector to the DOM element which will be shown as content in the viewport box. Possible values: HTMLElement, Array(HTMLElement [,HTMLElement]), jQueryObject, '.selector', false. In case if this option is not set or it is false all children elements the viewport element contains will be taken as a content.

height Default: false

Height of the content frame. If it is not set or set to false then the height of a content element passed throw the 'content' option will be taken, but only if the content isn't passed as array of elements. Works only if the 'width' option is set.

width Default: false

Width of the content frame. Works in the same way as 'height' option and also doesn't work if 'height' option isn't set.

position Default: 'center'

Starting position of the content frame in relation to the viewport frame. Possible values: 'center', 'top', 'bottom', 'left', 'right'. Also you can combine values: 'top left', 'top right', 'bottom left' etc...

contentClass Default: 'viewportContent'

Class name of the content frame's element.

binderClass Default: 'viewportBinder'

Class name of the binder frame's element.

Methods

update $(...).viewport('update');

Updates position and size of the binder frame and updates position of the content frame regarding the viewport frame size. This method should be called if viewport element's size is changed. Without params. Return value: jQueryObject.

size $(...).viewport('size' [, height, width]);

Setter/getter of the content frame's size. Useful when your content doesn't have static width and height. Return value: if parameters are not set - {height: [number], width: [number]}, else - jQueryObject.

height $(...).viewport('height' [, height]);

Setter/getter for the content frame's height. Useful when your content doesn't have static height. Return value: number / jQueryObject.

width $(...).viewport('width' [, width]);

Setter/getter for the content frame's width. Useful when your content doesn't have static width. Return value: number / jQueryObject.

content $(...).viewport('content');

Getter for the content frame's element. Useful when you have to make your content draggable or smth like that. Return value: jQueryObject.

binder $(...).viewport('binder');

Getter for the binder frame's element. Return value: jQueryObject.

Changelog

0.2.1

Bugfix to stop appending whitespaces or line breakes to the content frame as text nodes.

0.2.0

Added new option position to set the starting position of the content frame in relation to the viewport frame.

0.1.0

Initial release of jquery.viewport