Basic Requirements

The following requirements have to be met in order to use jsPanel:
  • jQuery 1.9.1 or greater (including jQuery 2.2.0)
  • jQuery UI 1.9 or greater with at least UI Core, Mouse, Widget, Draggable, Resizable (due to a bug in jQuery-UI 1.10.3 and 1.10.4
    I currently recommend using version 1.11.4)
  • HTML5/CSS3 compatible browser and the use of <!DOCTYPE html>
  • bootstrap only in case you want to use the bootstrap option of jsPanel.

The bootstrap option of jsPanel basically adds a few CSS classes to various elements of the jsPanel template in order to have the jsPanel styling adjust to the used bootstrap theme.

Globals: The jsPanel script exposes one global object jsPanel

Following code shows an example of how to load all required files

<!DOCTYPE html>
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>jsPanel - a jQuery Plugin</title>
        <!-- loading jQuery UI css (which theme doesn't matter for jsPanel) -->
        <link rel="stylesheet" href="//ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/themes/flick/jquery-ui.css" />
        <!-- loading Bootstrap css (required only when you intend to use option.bootstrap) -->
        <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css">
        <!-- loading font-awesome css (required only when you intend to use the font-awesome iconfont) -->
        <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
        <!-- loading jsPanel css -->
        <link href="jspanel/jquery.jspanel.css" rel="stylesheet">
    </head>
    <body>

        <!-- Your HTML goes here -->

        <!-- loading jQuery -->
        <script src="//ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script>
        <!-- loading jQuery UI javascript -->
        <script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
        <!-- loading Bootstrap javascript (required only when you intend to use option.bootstrap) -->
        <script src="//netdna.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>
        <!-- loading jsPanel javascript -->
        <script src="jspanel/jquery.jspanel.js"></script>
    </body>
</html>

$.jsPanel( {config} )

A major difference of jsPanel version 2 compared with version 1.x is that version 2 is a jQuery function rather than a jQuery method! So jsPanel version 2 has to be called on the jQuery object with either $.jsPanel() or jQuery.jsPanel()

$.jsPanel( {config} ) is a jQuery function. So in order to create a jsPanel the function has to be called directly on the jQuery object. $.jsPanel() will create one single jsPanel and append it to the first item of a jQuery collection specified in the configuration object. Defaults are set for every available option. Unlike other jQuery methods/functions $.jsPanel() will not iterate over a collection and append a panel to each item in the collection (only the first item in the collection gets a jsPanel).

The $.jsPanel() function takes one optional argument: the configuration object

The return value of the $.jsPanel() function is the jsPanel itself to allow for further chaining of other jQuery or jsPanel methods.

So the most basic way to create a jsPanel is:

$.jsPanel();

This example creates a jsPanel with all default options and appends the panel to the top left corner of the body element.

Execute example above

Using another element than the body as container for the jsPanel in combination with a few other options:

$.jsPanel({
    selector: "#container-1",
    position: "center",
    theme:    "success",
    title:    "Another jsPanel"
});

This example creates a jsPanel with almost all default options and appends the panel to the top left corner of the element specified by option.selector.

Execute example above

NOTE: If using a container for the jsPanel other than the body element the container has to be positioned using either absolute, relative or fixed.


jsPanel Options

Options can be passed to each individual jsPanel() function by use of a configuration object { options }. All available options of course have a default value that will be overridden whenever you configure other values for a given option. The following example sets title, size, position and theme of the jsPanel.

$.jsPanel({
    title:    "Title of the jsPanel",
    size:     { width:  400, height: 200 },
    position: 'center',
    theme:    'medium'
});
Execute example above

Available options include:

addClassadds custom css classes to header, content and footer sections API option.addClass
ajax loads content using jQuery.ajax()
read documentation
API option.ajax
autocloseenables automatic closing of a jsPanel after a specified time API option.autoclose
bootstrapin combination with option.theme enables automatic adaption to a used bootstrap theme API option.bootstrap
callbacka function or array of functions executed when the jsPanel is loaded into the document API option.callback
configallows the use of a predefined jsPanel configuration object API option.config
content loads content using jQuery's append() method
read documentation
API option.content
controlsconfigures the control buttons in the top right corner of the jsPanel API option.controls
dblclicksallows to bind doubleclick event handlers to title, content and/or footer sections API option.dblclicks
draggableconfigures jQuery's draggable interaction for the jsPanel API option.draggable
idsets the id attribute of the jsPanel API option.id
iframe configures an iframe as content of the jsPanel
read documentation
API option.iframe
load loads content using jQuery's .load() method
read documentation
API option.load
maximizedMargin sets individual jsPanel "margins" relative to browser viewport or jsPanel container
read documentation
API option.maximizedMargin
offset sets horizontal and/or vertical position offsets
read documentation
API option.offset
onbeforeclose takes a function to execute before the jsPanel closes. If function returns false panel will not close. API option.onbeforeclose
onbeforemaximize takes a function to execute before the jsPanel maximizes. If function returns false panel will not maximize. API option.onbeforemaximize
onbeforeminimize takes a function to execute before the jsPanel minimizes. If function returns false panel will not minimize. API option.onbeforeminimize
onbeforenormalize takes a function to execute before the jsPanel normalizes. If function returns false panel will not normalize. API option.onbeforenormalize
onclosed takes a function to execute after the jsPanel closed. API option.onclosed
onmaximized takes a function to execute after the jsPanel maximized. API option.onmaximized
onminimized takes a function to execute after the jsPanel minimized. API option.onminimized
onnormalized takes a function to execute after the jsPanel normalized. API option.onnormalized
overflowconfigures the overflow properties of the jsPanel content area API option.overflow
panelstatusBy default any new jsPanel will have a normalized status. option.panelstatus can be used to automatically maximize, minimize or smallify a jsPanel immediately after it was created. API option.panelstatus
paneltypesets the type of jsPanel. This can either be a standard jsPanel, a modal jsPanel, a tooltip or a hint API option.paneltype
position sets the position of the jsPanel relative to the containing element
read documentation
API option.position
removeHeaderallows to remove the header section from the jsPanel API option.removeHeader
resizableconfigures jQuery's resizable interaction for the jsPanel API option.resizable
rtlsupport for right-to-left text direction API option.rtl
selector specifies a container to append the jsPanel to
read documentation
API option.selector
showsets the animation used to blend in a jsPanel API option.show
sizesets the size of a jsPanel API option.size
templateallows use of a custom template for a specific jsPanel API option.template
themesets one of several themes of a jsPanel API option.theme
titlesets the title of a jsPanel API option.title
toolbarHeader configures a toolbar in the header section of a jsPanel
read documentation
API option.toolbarHeader
toolbarFooter configures a toolbar in the footer section of a jsPanel
read documentation
API option.toolbarFooter

jsPanel Properties

Available properties include:

jsPanel.headerrepresents the complete header section (including title, controls and toolbar) API property header
jsPanel.header.titlerepresents the h3 element containing the title text API property header.title
jsPanel.header.controlsrepresents the div element containing the control buttons (close, maximize, minimize, ...) API property header.controls
jsPanel.header.toolbarrepresents the div element containing the header toolbar API property header.toolbar
jsPanel.contentrepresents the div element containing the content of the jsPanel API property content
jsPanel.footerrepresents the div element containing the footer toolbar API property footer
jsPanel.statusis set to the current status (normalized, maximized, minimized, ...) of the jsPanel API property status
// create a jsPanel and store it in a variable
var mypanel = $.jsPanel({
    position: "center",
    theme: "autumnbrown"
});
// access the content property and log the status property to it
mypanel.content.append("<p style='...'><i>jsPanel</i>.status: " + mypanel.status + "</p>");
// use the "jspanelstatechange" event to log the final status
mypanel.on('jspanelstatechange', function(){
    mypanel.content.append("<p style='...'><i>jsPanel</i>.status changed to: " + mypanel.status + "</p>");
});
Execute example above

jsPanel Methods

A bunch of methods are provided that can either be chained directly to .jsPanel() or can be called on a variable representing a jsPanel.

Example using .title();

// create a jsPanel and store it in a variable
var panel1 = $.jsPanel({
    title:    "jsPanel Title",
    size:     { width: 400, height: 200 },
    position: "center",
    theme:    "success"
});

window.setTimeout( function(){
    // call .title() on the variable representing the jsPanel (delayed in order to see the title change)
    panel1.title('jsPanel <small>a jquery plugin</small>');
}, 3000);
Execute example above

Available methods include:

addToolbar()adds a toolbar either to the header section or the footer section of a jsPanel API method addToolbar()
close()closes a jsPanel anf removes it from the DOM API method close()
closeChildpanels()removes all jsPanels that are contained within another jsPanel API method closeChildpanels()
front()moves a jsPanel to the front by adjusting the z-index API method front()
control()disables/enables a control of an excisting jsPanel API method control()
maximize()maximizes a jsPanel either within its containing element or within the window API method maximize()
minimize()minimizes a jsPanel to the lower left corner of the window API method minimize()
normalize()normalizes a minimized jsPanel back to its original size and position API method normalize()
reloadContent()reloads content loaded with either option.load, option.ajax or option.iframe API method reloadContent()
reposition()repositions an already exsisitng jsPanel and optionally moves it from one container element to another API method reposition()
resize()resizes an already exsisitng jsPanel API method resize()
smallify()reduces the height of a jsPanel to the height of the header section API method smallify()
title()gets or sets the title text of a jsPanel API method title()

jsPanel Events

Following events are currently implemented in jsPanel:

jspanelloadedis triggered when the jsPanel is appended to the document and the entry animation completed - meaning the jsPanel is fully visible API event jspanelloaded
jspanelbeforecloseis triggered before the jsPanel is removed from the document API event jspanelclosed
jspanelclosedis triggered after the jsPanel is removed from the document API event jspanelbeforeclose
jspanelbeforeminimizeis triggered before the jsPanel starts minimizing API event jspanelbeforeminimize
jspanelminimizedis triggered after the jsPanel is minimized to the bottom left corner of the document API event jspanelminimized
jspanelbeforenormalizeis triggered before the jsPanel starts normalizing API event jspanelbeforenormalize
jspanelnormalizedis triggered after the jsPanel is restored to "normal" size and position from either a minimized, maximized or smallified status API event jspanelnormalized
jspanelbeforemaximizeis triggered before the jsPanel starts maximizing API event jspanelbeforemaximize
jspanelmaximizedis triggered after the jsPanel is maximized API event jspanelmaximized
jspanelsmallifiedis triggered after the jsPanel is smallified from a status other than maximized API event jspanelsmallified
jspanelsmallifiedMaxis triggered after the jsPanel is smallified from a maximized status API event jspanelsmallifiedMax
jspanelstatechangeis triggered after the status of the jsPanel changed API event jspanelstatechange

Important! The handler for the "jspanelclosed" event has to be attached to the <body> element.

// create a jsPanel and store it in a variable
var mypanel2 = $.jsPanel({
    position: "center",
    theme: "autumnred"
});
// bind a handler to the "jspanelstatuschange" event
mypanel2.on('jspanelstatechange', function(){
    if (mypanel2.status === "maximized" || mypanel2.status === "normalized") {
        mypanel2.content.append("<p style='...'><i>jsPanel</i>.status changed to: " + mypanel2.status + "</p>");
    }
});
Execute example above and click the maximize/normalize controls