jWindow: jQuery Windows Engine 2

a jQuery plugin that lets you create windowed user interfaces

Licence

jWindow: jQuery Windows Engine 2
Copyright (c) 2011 Dominik Marczuk
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * The name of Dominik Marczuk may not be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY DOMINIK MARCZUK "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL DOMINIK MARCZUK BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Credits

The original plugin, on which jWindow is based, is called jQuery Windows Engine. It was written by Hernán Amiune and licenced under the MIT licence.

What is jWindow, exactly?

jWindow is a jQuery plugin that lets you create windows that look and behave just like your OS, whichever that might be. It provides you with the $.jWindow object, which is both powerful and easily extensible, should you choose to add custom functionality.

Set up

jWindow requires no extra libraries other than jQuery. It must be version 1.7 or newer. If you wish to make it work with earlier versions of jQuery, you will need to modify the source code and replace all occurrences of the $.on() method with either $.live() or $.bind().

If you wish to use easing functions other than those that come with jQuery, you might also want to use jQuery UI's easing plugin.

You will also want to include a CSS theme for your windows.

So, the complete set up will require putting something like this in the page's <head> section:

<link type="stylesheet" href="themes/umbra/style.css" />
<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="jWindow-2.0.min.js"></script>

Basic features

Create a window

In order to create a new window, all you need to do is call the $.jWindow() method and pass it an object containing the new window's ID:

$.jWindow({ id: "demo" });

This will instantiate a window, but it will not display it. In order to actually make it appear on the screen, you also need to call the jWindow.show() method:

var w = $.jWindow({ id: "demo" });
w.show();

Or, to make it shorter:

$.jWindow({ id: "demo" }).show();

Close a window

A window can be closed by clicking its close button.

Programatically, you will want to use the hide() method:

$.jWindow("demo").hide();

Reference a window

Each window has a unique ID. No two windows with the same ID may exist. You may reference a window by passing $.jWindow() the ID string. If the window with the given ID does not exist, $.jWindow() will return null.

var w = $.jWindow("demo");

Other window states

The window can be minimised or maximised. The states can be switched by pressing the minimise and maximise buttons. Pressing them again will restore the window to its original state.

You can minimise, maximise and restore a window programatically:

$.jWindow("demo").maximise();
$.jWindow("demo").minimise();
$.jWindow("demo").restore();

Theming

The HTML structure generated by jWindow is the following:

<div id="demo" class="jWindow">
	<div class="jWindow-titleBar">
		<div class="jWindow-title"></div>
		<div class="jWindow-button jWindow-minimiseButton"></div>
		<div class="jWindow-button jWindow-maximiseButton"></div>
		<div class="jWindow-button jWindow-closeButton"></div>
	</div>
	<div class="jWindow-wrapper">
		<div class="jWindow-content"></div>
		<div class="jWindow-statusBar">
			<div class="jWindow-resizeIcon"></div>
		</div>
	</div>
</div>

If the window is modal, the above HTML is additionally wrapped in:

<div class="jWindow-modalBackground"></div>

Also, whenever the window is being dragged or resized, the content div is overlaid with an iframe cover:

<div class="jWindow-content">
	<div class="jWindow-iframeCover"></div>
</div>

The iframe cover is there to allow JavaScript to capture mouse events over an iframe, but it can be styled as well, for instance, to include a darker background.

jWindow makes sure certain necessary styles are applied, such as the correct positioning context. Other than that, the look of the divs is up to you.

The basic styling includes giving the title bar and the status bar a height and changing their respective background colours.

Please note that jWindow will apply additional classes on the window's root div (the one with the class .jWindow). These classes correspond to the states the window might be in: minimised, maximised. They can be used to apply different styling to the window depending on the state it's currently in.

API reference

The $.jWindow() method

The $.jWindow() method is the sole most important method that is handed to you. It acts as a window factory and getter.

$.jWindow(options)

This method is a window factory. It calls the jWindow constructor and returns the created object.

In case of an error (ie, missing ID), an exception is thrown.

If the provided ID is repeated, the already existing instance of jWindow will be returned instead of creating a new one.

Parametres
param type property type default value description
options object id string none Mandatory. The ID of the window that is being created. The function will fail if an ID is not specified or is not unique.
parentElement string "body" The selector of the element the window will be placed inside.
title string "" (empty string) Window title.
fixed boolean true Whether the window should have fixed positioning. If set to false, the positioning context will become absolute.
posx number 50 The offset from the left edge of the window (in pixels).
posy number 50 The offset from the top of the window (in pixels)
width number 300 The width of the window.
height number 200 The height of the window's content area (i.e., excluding the title and status bars)
onClose function null Callback function. Called after the window's close button is pressed.
onMinimise function null Callback function. Called after the window's minimise button is pressed.
onMaximise function null Callback function. Called after the window's maximise button is pressed.
onRestore function null Callback function. Called after the window has been restored from the minimised or maximised state using the minimise or maximise buttons.
onDragStart function null Callback function. Called when the window's dragging starts.
onDragEnd function null Callback function. Called when the window's dragging ends.
onResizeStart function null Callback function. Called when the window resizing starts.
onResizeEnd function null Callback function. Called when the window's resizing ends.
Return
type description
jWindow The newly created jWindow object. Provides a fluent interface. 
// minimal setup
var w = $.jWindow({
	id: "demo"
});
// all available options
var w = $.jWindow({
	id: "demo",
	title: "Demo window",
	width: 600,
	height: 400,
	posx: 100,
	posy: 100
});

$.jWindow(id)

This method is a getter. It fetches an already existing instance of jWindow.

If the specified ID is not valid (ie, a window with that ID doesn't yet exist), the method returns null.

Parametres
param type property type default value description
id string none Mandatory. The ID of the window that is being retrieved. The function will fail if an ID is not specified.
Return
type description
jWindow The retrieved jWindow object. Provides a fluent interface.
null In case the requested ID is not among the already created windows. 
var w = $.jWindow("demo");

Public methods

Once a jWindow object has been created/fetched, it is possible to call several public methods on it, enabling its manipulation.

show([params])

Displays a window. The window will appear with an animation.

The show() method can be called with several different parametres:

  • show()
  • show(duration)
  • show(easing)
  • show(complete)
  • show(options)

All parametres control the window's animation.

Parametres
param type property type default value description
duration number 350 The duration of the animation, in milliseconds.
easing string "linear" The animation's easing.
complete function function () {} The callback, called after the animation is complete.
options object duration number 350 The duration of the animation, in milliseconds.
easing string "linear" The animation's easing.
complete function function () {} The callback, called after the animation is complete.
Return
type description
jWindow The jWindow object the function has been called on. Provides a fluent interface. 
var w = $.jWindow("demo");
w.show();
w.show(1000);
w.show({
	duration: 1000,
	easing: "swing",
	complete: function() {
		alert("Something has happened!");
	}
});
// chaining
w.show().maximise();

hide([params])

Closes a window. The window will disappear with an animation. The DOM node is not removed, but rather detached, enabling you to call show() again when appropriate.

The hide() method can be called with the exact same parametres as show().

isHidden()

Checks whether the window is hidden or not.

Return
type description
boolean true if the window is hidden, false it it is visible.

maximise([params])

Maximises a window. The window will resize itself with an animation, taking up the entire window's space.

The maximise() method can be called with the exact same parametres as show().

minimise([params])

Minimises a window. The window will fold itself the the title bar only with an animation.

The minimise() method can be called with the exact same parametres as show().

restore([params])

Restores a window from either the minimised or maximised state (or both).

The restore() method can be called with the exact same parametres as show(). Additionally, there's also a possibility to specify whether the window should be restored from minimised or maximised state.

Parametres
param type property type default value description
duration number 350 The duration of the animation, in milliseconds.
easing string "linear" The animation's easing.
complete function function () {} The callback, called after the animation is complete.
options object duration number 350 The duration of the animation, in milliseconds.
easing string "linear" The animation's easing.
complete function function () {} The callback, called after the animation is complete.
type string "both" Whether to restore the window from the minimised, maximised or both states. Accepted values are: "min", "max" and "both".
Return
type description
jWindow The jWindow object the function has been called on. Provides a fluent interface.

refresh()

Refreshes the content of the window. This method does not care about the jWindow's url option and only reloads the location currently displayed.

Return
type description
jWindow The jWindow object the function has been called on. Provides a fluent interface.

focus([focus])

Focuses or blurs a window. If a window is put in focus, all others are blurred.

Parametres
param type property type default value description
focus boolean true true or no parametre to focus the window, false to blur it.
Return
type description
jWindow The jWindow object the function has been called on. Provides a fluent interface. 
var w = $.jWindow("demo");
w.focus(); // focus
w.focus(false); // blur

hasFocus()

Checks whether a window is focused or blurred.

Return
type description
boolean true if the window is in focus, false otherwise. 
var w = $.jWindow("demo");
w.focus(); // focus
alert(w.hasFocus());
w.focus(false); // blur
alert(w.hasFocus);

set(param[, value])

Sets the value of an option or a number of options. The method can be called with either two parametres or a map of parametres and their values.

The following options can be set:

  • title
  • posx
  • posy
  • width
  • height
  • resizeable
  • draggable
  • onDragStart
  • onDragEnd
  • onResizeStart
  • onResizeEnd
  • onUpdate
  • onClose
  • onMaximise
  • onRestore
  • onMinimise
  • url
  • tabs

set(param, value)

Parametres
param type property type default value description
param string The name of the option.
value mixed The value of the option.
Return
type description
jWindow The jWindow object the function has been called on. Provides a fluent interface. 
var w = $.jWindow("demo");
w.set('onDragEnd', function() { alert('dragged'); });

set(param)

Parametres
param type property type default value description
param object A map of the options and their values.
Return
type description
jWindow The jWindow object the function has been called on. Provides a fluent interface. 
var w = $.jWindow("demo");
w.set({
    onDragEnd:   function() { alert('dragged'); },
    onResizeEnd: function() { alert('resized'); ),
    title:       'New title'
});

get(param)

Retrieves the value of any options variable.

Parametres
param type property type default value description
param string The name of the option to retrieve.
Return
type description
mixed The requested option's value. 
var w = $.jWindow({ id: 'demo', url: 'http://www.bing.com' });
alert(w.get('url')); // alerts "http://www.bing.com"
w.set({ url: 'http://www.google.com' });
alert(w.get('url')); // alerts "http://www.google.com"

appendTab(params)

Adds a window tab and places it at the end of the current tabs list.

Parametres
param type property type default value description
params object href string Mandatory property. The URL the tab is going to link to.
title string Mandatory property. The text that is going to be displayed on the tab.
name string Optional property. The name that will be used to reference the tab.
Return
type description
jWindow The jWindow object the function has been called on. Provides a fluent interface. 
var w = $.jWindow({ id: "demo", tabs: true });
w.appendTab({
    href: '/',
    title: 'Main page'
}).show();

prependTab(params)

Adds a window tab and places it at the beginning of the current tabs list.

Accepts the same parametres as appendTab().

var w = $.jWindow({ id: "demo", tabs: true });
w.prependTab({
    href: '/',
    title: 'Main page'
}).show();