jsPanel 1.11 a jQuery plugin to create multifunctional floating panels

API jsPanel version

Options

Setting options in the configuration object of the .jsPanel() function will set options for the individual jsPanel. It will not change options globally. To see how to change the defaults globally go down to the defaults section.

option.ajax

version 1.0 | last update 1.1

This option is one of several ways to load content into the jsPanel. Additional ways to load content are provided by option.content and option.load. Option.load internally uses the native jQuery method .load()

Type: object

Default: false

The settings of the option.ajax configuration object are used the same way as the arguments for jQuery.ajax() are used.

For detailed information about the jQuery.ajax() configuration refer to the jQuery API

$( '#option-ajax' ).jsPanel({
    size:      { width: 440, height: 'auto' },
    theme:     'info',
    overflow:  'hidden',
    ajax: {
        url: 'files/example-ajax.html'
    }
});

As of version 1.1.0 the option.ajax settings object accepts the following additional settings:

  • done: function( data, textStatus, jqXHR, jsPanel ) {}
    A function that will be passed to jQuerys .done() callback and receives the same arguments as jQuerys .done() callback plus the jsPanel as fourth argument.
  • fail: function( jqXHR, textStatus, errorThrown, jsPanel ) {}
    A function that will be passed to jQuerys .fail() callback and receives the same arguments as jQuerys .fail() callback plus the jsPanel as fourth argument.
  • always: function( data|jqXHR, textStatus, jqXHR|errorThrown, jsPanel ) {}
    A function that will be passed to jQuerys .always() callback and receives the same arguments as jQuerys .always() callback plus the jsPanel as fourth argument.
    In response to a successful request, the function's arguments are the same as those of .done(): data, textStatus, and the jqXHR object plus the jsPanel as fourth argument.
    For failed requests the arguments are the same as those of .fail(): the jqXHR object, textStatus, and errorThrown plus the jsPanel as fourth argument.
  • then: function( data, textStatus, jqXHR, jsPanel ) {}, function( jqXHR, textStatus, errorThrown, jsPanel ) {}
    Expects an array of two functions. The first function serves as callback for a successful request, the second one as callback for a failed request.
$( '#option-ajax' ).jsPanel({
    size:      'auto',
    position:  { top: 770, left: 15},
    theme:     'info',
    overflow:  'hidden',
    ajax: {
        url:    'files/example-ajax-2.html',
        done:   function( data, textStatus, jqXHR, jsPanel ){
            console.log( 'jqXHR status: ' + jqXHR.status + ' ' + jqXHR.statusText + ' ' + textStatus  );
        },
        fail:   function( jqXHR, textStatus, errorThrown, jsPanel ){
            $( '.jsPanel-content', jsPanel ).append( jqXHR.responseText );
        },
        always: function( arg1, textStatus, arg3, jsPanel ){
            console.log( textStatus );
        }
    }
});
$( '#option-ajax' ).jsPanel({
    size:      'auto',
    position:  { top: 1187, left: 15},
    theme:     'info',
    overflow:  'hidden',
    ajax: {
        url: 'files/example-ajax-3.html',
        then: [
            function( data, textStatus, jqXHR, jsPanel ){
                jsPanel.title( 'Example for option.ajax.then' );
                console.log( textStatus )
            },
            function( jqXHR, textStatus, errorThrown, jsPanel ){
                $( '.jsPanel-content', jsPanel ).append( jqXHR.responseText );
                console.log( errorThrown )
            }
        ]
    }
});

option.autoclose

version 1.2

This option allows the jsPanel to close automatically after the specified time in milliseconds.

Type: number

Default: false

$('#option-autoclose').jsPanel({
    autoclose: 4000,
    theme:     'success',
    overflow:  'hidden'
});
and wait a few seconds to see the jsPanel close automatically

option.content

version 1.0

This option is one of several ways to load content into the jsPanel. Additional ways to load content are provided by option.load and option.ajax.

Type: string | function | jQuery object

Default: false

$( '#option-content' ).jsPanel({
    content: "<div class='preloader'><img src='images/pl.gif'></div>",
    position: 'center'
});
$('#option-content').jsPanel({
    content: function(){ return "<div class='preloader'><img src='images/pl.gif'></div>"; },
    position: 'center'
});
$('#option-content').jsPanel({
    content: $( '<p>Lorem ipsum ...</p>' ).css( {padding:'20px', 'text-align':'center'} ),
    position: 'center'
});

option.controls

version 1.2 | last update 1.4

This option allows to configure the buttons in the header.

Type: object

Default: { buttons: "all", iconfont: false }

Possible values for buttons:

  • string 'all' is the default and shows all control buttons.
  • string 'closeonly' which will show the close button only.

Possible values for iconfont:

  • bolean false is the default and shows the standard icon sprite images.
  • string 'font-awesome' | 'bootstrap' will show the respective iconfont./li>
$('#option-controls').jsPanel({
    size:     { width: 300, height: 170 },
    overflow: 'hidden',
    position: { top: 150, right: 50 },
    controls: { buttons: 'closeonly', iconfont: 'font-awesome' }
});

Icon fonts are not included in jsPanel by default. You have to include the necessary files/scripts yourself in order to use icon fonts.

To use font-awesome for example include the following code in the head section of your document.

<link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">

To use the bootstrap glyphicons include ...

<!-- compiled and minified CSS -->
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
<!-- compiled and minified JavaScript -->
<script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
$('#option-controls').jsPanel({
    size:     { width: 300, height: 200 },
    overflow: 'hidden',
    position: { bottom: 100, right: 70 },
    controls: { buttons: 'all', iconfont: 'bootstrap' }
});

For detailed infos about bootstrap go to getbootstrap.com

For detailed infos about font-awesome go to fortawesome.github.io/Font-Awesome

option.draggable

version 1.0 | last update 1.2

Type: object | string

Default: The jQuery-UI draggable interaction is enabled on all jsPanels with the following options:

For childpanels the draggable feature is enabled with containment set to "parent".

{
    handle:  'div.jsPanel-hdr',
    stack:   '.jsPanel',
    opacity: 0.6
}

You can change the draggable options to your needs by adding them to the configuration object of the jsPanel. Let's say you want to add a callback to the stop event and further want to confine dragging of the jsPanel to the containing element. You would do it like this:

$('#option-draggable').jsPanel({
    draggable: {
        stop: function( event, ui ) {
            ui.helper.css( 'background', '#fedfed' );
        },
        containment: '#option-draggable'
    },
    position: { top: 70, left: 'center' }
});
and drag the jsPanel a few pixels

This will change the background color of the jsPanel itself after dragging is finished.

For detailed information on how to use the jQuery-UI draggable interaction see the jQuery UI api documentation

Disable the draggable feature completely by setting option.draggable to "disabled".

$('#option-draggable').jsPanel({
    draggable: "disabled",
    position:  { bottom: 30, right: 30 }
});

option.header

version 1.8

This option allows to remove the header section of the jsPanel completely.

Type: boolean true | false

Default: true

Use option.header with care since all the control buttons will be gone as well unless you add the required controls in a footer toolbar.

var arr = [
    {
        item: '<button class="..." type="button"><span class="..."></span> Close</button>',
        event: 'click',
        callback: function(){ hdr_panel.close() }
    }
];

var hdr_panel = $("#option-header").jsPanel({
    header: false,
    toolbarFooter: arr,
    overflow: 'hidden',
    position: 'center'
});

option.id

version 1.0 | last update 1.5

This option will set the value of the id attribute of the outermost div element of the jsPanel.

Type: string | function

Default: as generated by jQuery.fn.uniqueId.

If option.id is a string and already exists in the document, it will be ignored and another id will be generated as described above. The new id will be attached to the title of the jsPanel as a reminder. Click the first example below more than once to see the effect.

$( '#option-id' ).jsPanel({
    id: 'testpanel',
    position: { top: 'auto', right: 'auto'}
}, function( jsPanel ){
    $( '.jsPanel-content', jsPanel ).html( '<p style="padding:20px;">id: ' + jsPanel.attr('id') + '</p>' )
});
$('#option-id').jsPanel({
    id: function(){ return 'jsPanel_' + ( $('.jsPanel').length + 1 ) },
    position: { bottom: 'auto', right: 'auto'}
}, function( jsPanel ){
    $( '.jsPanel-content', jsPanel ).html( '<p style="padding:20px;">id: ' + jsPanel.attr('id') + '</p>' )
   }
);

option.load

version 1.0

This option is one of several ways to load content into the jsPanel. Additional ways to load content are provided by option.content and option.ajax. Option.load internally uses the native jQuery method .load()

Type: object

Default: false

The settings of the option.load configuration object are used the same way as the arguments for jQuery .load() are used.

For detailed information about the jQuery .load() configuration refer to the jQuery API.

Possible values for url, data and complete:

  • url: A string containing the URL to which the request is sent.
  • data: A plain object or string that is sent to the server with the request.
  • complete: A callback function that is executed when the request completes. This callback function receives the same 3 arguments as the native jQuery.load() complete callback. Additionally it receives the jsPanel as fourth argument.
$( '#option-load' ).jsPanel({
    size:      'auto',
    theme:     'info',
    overflow:  'hidden',
    load: {
        url: 'files/example-load.html',
        complete: function( responseText, textStatus, XMLHttpRequest, jsPanel ){
            console.log( textStatus );
            $( '.jsPanel-content', jsPanel ).append( XMLHttpRequest.statusText );
        }
    }
});

option.modal

version 1.5 | last update 1.6.2

With this option enabled a modal jsPanel will be created.

Type: boolean | string

Default: false

Possible values for option.modal: true | false | 'modal-ok' | 'modal-yesno' | 'modal-confirm' | 'modal-submit'

With option.modal set to true:

  • a modal jsPanel will always be appended to a special helper element
  • the position of the jsPanel will always be centered, regardless of what is set in option.position
  • the controls show only the close button, regardless of what is set in option.controls
  • draggable and resizable capabilities are set to 'disabled', regardless of what is set in the configuration objects

The footer toolbar - if needed - has to be configured with option.toolbarFooter

$( '#option-modal' ).jsPanel({
    modal:    true,
    controls: { iconfont: 'bootstrap' },
    overflow: 'hidden',
    theme:    'medium'
});

As of version 1.6 modal presets for various standard situations are included:

To activate the presets set option.modal to either 'modal-ok' | 'modal-yesno' | 'modal-confirm' | 'modal-submit'. This will configure a predefined footer toolbar where only the buttontext and callback functions for the buttons have to be set.

When using one of this values for option.modal you have to provide an array in option.toolbarFooter. Each array item has to be an object and represents a <button> element. Required elements in each object are:

  • buttontext: the text to show on the <button>. buttontext is provided to enable a localized usage of the modal presets.
  • buttonclass: (optional, added in 1.6.2) a classname to add to the <button> element. If not set defaults to "btn-sm"
  • callback: the function to call when the button is clicked

Modal types:

  • modal-ok adds a footer toolbar with an Ok button
  • modal-yesno adds a footer toolbar with a Yes and a No button
  • modal-confirm adds a footer toolbar with a Confirm and a Cancel button
  • modal-submit adds a footer toolbar with a Submit and a Cancel button

Example for a modal-yesno:

var mp_yesno = $( '#option-modal' ).jsPanel({
    title: 'Modal Yes or No',
        modal: 'modal-yesno',
        controls: { iconfont: 'bootstrap' },
        overflow: 'hidden',
        size: { width: 300, height: 185 },
        theme: 'medium',
        toolbarFooter: [
            {
                buttontext: 'Yes',
                buttonclass: 'btn-xs',
                callback:   function(){ alert('You clicked the Yes button!') }
            },
            {
                buttontext: 'No',
                buttonclass: 'btn-xs',
                callback:   function(){ mp_yesno.close(); }
            }
        ]
});

option.overflow

version 1.0 | last update 1.2

This option will set the css overflow property or the css overflow-y / overflow-x properties of the div element containing the content of the jsPanel.

Type: string | object

Default: "hidden"

Using option.overflow with a string:

Passing a string will set the css overflow property to "string"

Possible values are: "visible" | "hidden" | "scroll" | "auto" | "initial" | "inherit"

$( '#option-overflow' ).jsPanel({
    overflow: 'scroll',
    position: 'top right',
    size:     { width: 440, height: 300 },
    load:     { url: 'files/loremipsum.html' },
    theme:    'warning'
});

Using option.overflow with an object:

Passing an object will set css overflow-y and overflow-x properties

Possible values for the two parameters horizontal and vertical are: "visible" | "hidden" | "scroll" | "auto" | "initial" | "inherit"

$( '#option-overflow' ).jsPanel({
    overflow: { horizontal: 'hidden', vertical: 'scroll' },
    position: { top: 400, right: 50 },
    size:     { width: 440, height: 300 },
    load:     { url: 'files/loremipsum.html' },
    theme:    'warning'
});

option.position

version 1.0 | last update 1.7.1

This option will set the position of the jsPanel relative to the parent element containing the jsPanel. The parent element needs to be positioned somehow for option.position to work as expected.

Type: string | object

Default: "auto"

jsPanels are positioned absolute

So the jsPanel is positioned relative to its first positioned (not static) ancestor element. Consider this when placing the jsPanel within a container that is not positioned accordingly.

"center" options in combination with width: "auto" and/or height: "auto"

To center the jsPanel properly the size of the jsPanel has to be known when calculating the position. That might not be the case when loading content is delayed somehow (using a function/ajax request to get the content).

Using option.position with a string:

The following shortcuts are provided for some standard positions:

  • "auto" as shortcut for { top: "auto", left: "auto" }
  • "center" as shortcut for { top: "center", left: "center" }
  • "top left", "top center", "top right", "center right", "bottom right", "bottom center", "bottom left", "center left"
$('body').jsPanel({
    position: 'auto'
});
Click repeatedly to see the effect of automatic positioning.
$('body').jsPanel({
    size: 'auto',
    position: 'center',
    content: "<p style='padding:100px;'>Some text content ...</p>"
});
$('body').jsPanel({
    size: 'auto',
    position: 'top center',
    content: "<p style='padding:40px 100px;'>Some other content ...</p>"
});

Using option.position with an object:

When using an object a feasible combination of two parameters out of the following 4 options is expected: "top", "left", "bottom", "right"

Possible values for "top", "left", "bottom", "right": integer | string | "auto" | function

  • An integer will be interpreted as pixel value
  • A string will be parsed using parseInt() and the result will be used as pixel value when the jsPanel is appended to the body element. If the jsPanel is appended to an element other than the body you can use any string that is valid for css top, left, bottom or right e.g. '50%'.
  • "auto" will automatically position the jsPanel. Each additional jsPanel will be offset by 25 pixels.
  • "center" will center the jsPanel either horizontally or vertically or both.
  • "top", "left", "bottom" or "right" also accept a function( jsPanel ) as value. The return value of the function will be parsed using parseInt() and used to set css "top", "left", "bottom" or "right" of the jsPanel. The function receives the jsPanel as Argument.
$('#option-position').jsPanel({
    position: { top: 940, left: 300 }
});
$('#option-position').jsPanel({
    position: { top: '1070px', left: 'center' }
});
$('#option-position').jsPanel({
    position: {
        bottom: function( jsPanel ){ return jsPanel.parent().height()/5 },
        left: 'center'
    }
});

Using option.position.bottom and/or option.position.right
jQuery UI's draggable/resizable interactions work by manipulating the css top and left values. When a jsPanel has right and/or bottom values set (and no static width/height), the jsPanel would show a strange behaviour when dragged or resized.

To have the draggable and resizable features work as intended when using option.position.bottom and/or option.position.right in combination with option.size.width and/or option.size.height set to 'auto' any set values for option.position.bottom and/or option.position.right are recalculated to values for top and left after the jsPanel becomes visible in order to have a jsPanel with only top and left values applied.

$('#option-position').jsPanel({
    position: { bottom: 100, right: 100 },
});

Positioning of jsPanels appended directly to the <body> element ...
... works different. To see the difference execute the two examples below.

$('#positioning-standard').jsPanel({
    position:  { bottom: 'auto', right: 'auto' },
    size:      { width: 350, height: 150 },
    content:   "Standard positioning. jsPanel is not created directly within the body element."
});
$('body').jsPanel({
    position:  { bottom: 'auto', right: 'auto' },
    size:      { width: 350, height: 150 },
    content:   "This jsPanel is created directly within the body element."
});

So when you append a jsPanel directly to the <body> element the values for the option.position properties are more like offsets to the window rather than absolute positions within the body element.

Further a jsPanel appended to the body element will maximize within the window and not within the body element.

option.resizable

version 1.0 | last update 1.2

Type: object | string

Default: The jQuery-UI resizable interaction is enabled on all jsPanels with the following options:

{
    handles:   'e, s, w, se, sw',
    autoHide:  false,
    minWidth:  150,
    minHeight: 100
}

You can change the resizable options to your needs by adding them to the configuration object of the jsPanel. Let's say you want to add maxWidth and maxHeight values. You would do it like this:

$('#option-resizable').jsPanel({
    resizable: {
        maxWidth: 600,
        maxHeight: 350
    }
});

This will add values for the maxWidth/maxHeight options of the jQuery-UI resizable interaction while preserving the other default options.

For detailed information on how to use the jQuery-UI resizable interaction see the jQuery UI api documentation

Disable the resizable feature completely by setting option.resizable to "disabled".

$('#option-resizable').jsPanel({
    resizable: "disabled"
});

option.restoreTo

version 1.7

This option applies only to jsPanels appended to the <body> element.

By default minimized jsPanels when maximized again will restore their old position prior minimizing. With option.restoreTo you can override the default and force a minimized jsPanel to restore to a position at the top left corner of the browser viewport. That might be usefull when you scrolled the window after minimizing a jsPanel.

Type: boolean | "top_left"

Default: false

$('body').jsPanel({
    restoreTo: 'top_left',
    position:  'center'
});

option.rtl

version 1.10

Using this option switches a jsPanel to right-to-left text direction.

Type: object

Default: rtl: { rtl: false }

Object properties are:

  • rtl: boolean true|false
  • lang (optional): language code according to ISO 639-1
$('#option-rtl').jsPanel( {
    rtl: {
        rtl: true,
        lang: 'he'
    },
    title:    'כותרת פנל',
    content:  '<p/> זה הוא אזור התוכן של הלוח <p>',
    position: { top: 42, right: 10 }
})
var tbHdr = [
	{
        item: '<i class="fa fa-copy" style="cursor:pointer;margin-right:5px;">',
        event: 'click',
        callback: function(){ alert('You clicked on copy ...') }
    },
        {
        item: '<i class="fa fa-paste" style="cursor:pointer;margin-right:5px;">',
        event: 'click',
        callback: function(){ alert('You clicked on paste this time ...') }
    },
    {
        item: '<i class="fa fa-print" style="cursor:pointer;margin-right:5px;">',
        event: 'click',
        callback: function(){ alert('Nothing to print here ...') }
    }
];
var tbFtr = [
    {
        item: '<button class="btn btn-default btn-sm" type="button" style="float:left;"><span class="glyphicon glyphicon-ok" style="padding:0 5px 0 0;"></span>حسنا  </button>',
        event: 'mouseover',
        callback: function(){ alert('وكان هذا الفأرة'  ) }
    },
    {
        item: '<button class="btn btn-default btn-sm" type="button" style="float:left;"><span class="glyphicon glyphicon-remove" style="padding:0 5px 0 0;"></span>إلغاء </button>',
        event: 'click',
        callback: function(){ rtl_panel.close() }
    },
    {
        item: '<div style="float:right;cursor:pointer;padding:10px 10px 0 0">نص بسيط</div>',
        event: 'click',
        callback: function( event ) {
            alert( "حدث النقر في (" + event.pageX + ", " + event.pageY + ")" );
        }
    }
];
var rtl_panel = $('#option-rtl').jsPanel( {
    rtl: {
        rtl: true,
        lang: 'ar'
    },
    title:    'عنوان وحة',
    content:  '<p>هذا هو المجال المحتوى من لوحة</p>',
    position: { top: 1000, right: 10 },
    toolbarHeader: tbHdr,
    toolbarFooter: tbFtr
})
var mp_yesno = $( '#option-modal' ).jsPanel({
    title: 'عنوان وحة',
    modal: 'modal-yesno',
    rtl: {
        rtl: true,
        lang: 'ar'
    },
    size: { width: 300, height: 185 },
    toolbarFooter: [
        {
            buttontext: 'نعم',
            buttonclass: 'btn-xs',
            callback: function(){ alert('نقرت على زر نعم') }
        },
        {
            buttontext: 'لا',
            buttonclass: 'btn-xs',
            callback: function(){ mp_yesno.close(); }
        }
    ]
});

option.show

version 1.6

With this option you can specify the method/animation used to blend in the jsPanel.

Type: string

Default: "fadeIn"

Possible values currently are:

A string without a space serves as identifier for a method that is used to blend in the jsPanel. So option.show: "fadeIn" will result in jsPanel.fadeIn();

A string with at least one space is regarded as a collection of class names to add to the jsPanel. So option.show: "magictime twisterInDown" will result in jsPanel.addClass( option.show ). This basically adds support of pure css animations used to blend in the jsPanels instead of javascript methods/functions.

There are no css animations included in jsPanel by default. You have to provide them yourself.

Examples for css animations:

$( '#option-show' ).jsPanel({
    show: "slideDown",
    size: { width: 400, height: 245 }
});
$( '#option-show' ).jsPanel({
    show:     "magictime twisterInDown",
    size:     { width: 400, height: 245 },
    position: 'center'
});

option.size

version 1.0 | last update 1.11

As of version 1.11 option.size will set width and height of the content area of the jsPanel rather than width and height of the jsPanel as a whole!

Type: string | object

Default: { width: 400, height: 222 }

Using option.size with a string:

"auto" is currently the only valid string you can use with option size. This will set both width and height of the content div to "auto" and adjusts the size depending on the content. Using size: "auto" is equivalent to using size: { width: "auto", height: "auto" }

Using option.size with an object:

When using an object the two parameters "width" and "height" are expected.

Possible values for the parameters "width" and "height": integer | string | "auto" | function

  • An integer will be interpreted as pixel value
  • A string can be any valid value for css width and height.
  • The string "auto" will set the width and/or height depending on the content of the jsPanel.
  • width and/or height also accept a function( jsPanel ) as value. The return value of the function will be used to set css width and/or height of the content div. The function receives the jsPanel as argument.
$('#option-size').jsPanel({
    size:     { width: 430, height: 270 },
    position: { top: 150, right: 50 },
    controls: { iconfont: 'font-awesome' }
});
$('#option-size').jsPanel({
    size:     'auto',
    position: 'center',
    content:  "<p style='padding:50px 80px;'>Some text content for the demo ...</p>",
    controls: { iconfont: 'font-awesome' }
});
$('#option-size').jsPanel({
    size:     { width: 'auto', height: 300 },
    position: 'center',
    content:  "<p style='padding:30px 50px;'>Some more content for the demo ...</p>",
    controls: { iconfont: 'font-awesome' }
});
$('#option-size').jsPanel({
    size: {
        width: function(){ return $(window).width()/3 },
        height: 350
    },
    position: { bottom: 100, left: 'center' },
    content:  "<div class='...'><p style='padding:30px 50px;'>Width calculated by a function</p></div>"
});

option.statusbar

version 1.11

This option provides a means to reduce height of the toolbarFooter to 23px. A default toolbarFooter has a height of 46px. But there might be situations where you prefer a smaller toolbarFooter to act more as a statusbar.

Type: boolean true | false

Default: false

var tbf = [
    {
        item: '<div style="float:left;padding:0 0 0 5px;">Simple Text ...</div>',
        event: 'click',
        callback: function( event ) {
            alert( "The click happened at (" + event.pageX + ", " + event.pageY + ")" );
        }
    }
];
$( '#option-statusbar' ).jsPanel({
    statusbar: true,
    toolbarFooter: tbf,
    overflow: 'hidden',
    position: { top: 200, left: 380 }
});
var tbh = [
    {
        item: '<i class="fa fa-print" style="cursor:pointer;">',
        event: 'click',
        callback: function(){ alert('Nothing to print here ...') }
    }
];
var tbf = [
    {
        item: '<div style="float:left;padding:0 0 0 5px;">Simple Text ...</div>',
        event: 'click',
        callback: function( event ) {
            alert( "The click happened at (" + event.pageX + ", " + event.pageY + ")" );
        }
    }
];
$( '#option-statusbar' ).jsPanel({
    statusbar: true,
    toolbarFooter: tbf,
    toolbarHeader: tbh,
    overflow: 'hidden',
    position: { top: 690, left: 380 }
});

option.theme

version 1.5

This option will set one of various themes for the individual jsPanel. Currently included themes are: light, medium, dark, primary, success, info, warning, danger. Themes light, medium and dark are rather neutral grayscale themes, while the others are quite similar to the bootstrap coloring and are named accordingly.

Type: string

Default: 'light'

$( '#option-theme' ).jsPanel({
    theme: 'light'
});

option.title

version 1.0

This option will set the value of the title/header of the jsPanel.

Type: string | function

Default: a function building a default string like "jsPanel No 1", "jsPanel No 2", "jsPanel No 3", and so on.

To set an empty title/header use the option with an empty string.

$( '#option-title' ).jsPanel({
    title: 'Title of the jsPanel',
    position: { top: 'auto', right: 'auto'}
});
$('#option-title').jsPanel({
    title: function(){ return 'jsPanel No ' + ( $('.jsPanel').length ) },
    position: { top: 'auto', right: 'auto'}
});

option.toolbarHeader

version 1.6

This option allows to configure a toolbar in the header of the jsPanel.

Type: htmlString | Array

Default: false

Using option.toolbarHeader with a htmlString simply appends the passed htmlString to the toolbar.

Using option.toolbarHeader with an array allows to configure a number of items to append to the toolbar where each item can have its own event/callback assigned to. For detailed infos on how to use this option with an array refer to option.toolbarFooter that operates in the same way.

$('#option-toolbarHeader').jsPanel({
    controls: { iconfont: 'bootstrap' },
    overflow: 'hidden',
    toolbarHeader: [
        {
            item: '<i class="fa fa-copy" style="cursor:pointer;">',
            event: 'click',
            callback: function(){ alert('You clicked on copy ...') }
        },
        {
            item: '<i class="fa fa-paste" style="cursor:pointer;margin-left:5px;">',
            event: 'click',
            callback: function(){ alert('You clicked on paste this time ...') }
        },
        {
            item: '<i class="fa fa-print" style="cursor:pointer;margin-left:5px;">',
            event: 'click',
            callback: function(){ alert('Nothing to print here ...') }
        }
    ]
});

option.toolbarFooter

version 1.6

This option allows to configure a footer toolbar for the jsPanel.

Type: htmlString | Array

Default: false

Using option.toolbarFooter with a htmlString simply appends the passed htmlString to the toolbar.

Using option.toolbarFooter with an array allows to configure a number of items to append to the toolbar where each item can have its own event/callback assigned to. When using an array each array item has to be an object and represents an item to add to the toolbar.Each object is expected to have the following properties:

  • item is the element to append to the footer toolbar. Typically this is an htmlString, but can be anything accepted by jQuerys .append() method.
  • event is a string with the event that's supposed to trigger the callback like 'click', 'mouseover' and so on.
  • callback is a function to execute when event is triggered. The function gets the event object as argument.
var arr = [
    {
        item: '<div style="float:left;padding:10px 0 0 15px">Simple Text ...</div>',
        event: 'click',
        callback: function( event ) {
                    alert( "The click happened at (" + event.pageX + ", " + event.pageY + ")" );
                  }
    },
    {
        item: '<button class="..." type="button"><span class="..."></span> Cancel</button>',
        event: 'click',
        callback: function(){ fb_panel.close() }
    },
    {
        item: '<button class="..." type="button"><span class="..."></span> OK</button>',
        event: 'mouseover',
        callback: function(){ alert( 'And this was a mouseover' ) }
    }
];
     
var fb_panel = $("#option-toolbarFooter").jsPanel({
    toolbarFooter: arr,
    overflow: 'hidden',
    controls: { iconfont: 'bootstrap' },
    position: 'center'
});

option.tooltip

version 1.9

This option implements a basic tooltip functionality. The tooltip will appear either top, right, bottom or left of the element the tooltip is applied to. Depending on the configuration you can create a tooltip using almost all of jsPanel's options or rather create a tooltip that resembles more a classic tooltip.

The following limitations apply to all tooltips:

  • The features resizable and draggable will not be initialized regardless of the setting in option.resizable and option.draggable respectively.
  • The controls will show the close button only in case the header section is used at all.

Type: object

Default: false

Object properties:

  • position: string can be either 'top' | 'bottom' | 'left' | 'right' and sets the position of the tooltip relativ to the triggering element.
  • offsetX: integer (optional) will be used as horizontal offset
  • offsetY: integer (optional) will be used as vertical offset
  • mode: string (optional) 'sticky' | 'semisticky'

Basic mouseover examples

Example codes of the top tooltips above:

$('#tooltip_1').mouseenter( function(e){
    $('#tooltip_1')
        .jsPanel({
            tooltip: {
                position: 'left',
                offsetX: -5
            },
            size: { width: 250, height: 154 },
            title: 'Tooltip left'
        });
});
$('#tooltip_2').mouseenter( function(e){
    var tooltip1 = $('#tooltip_2')
        .jsPanel({
            tooltip: {
                    position: 'top',
                    offsetY: -5,
                    mode: 'sticky'
                   },
            size: { width: 300, height: 185 },
            title: 'tooltip top',
            content: '<p style="text-align:center">Do you like it?</p>',
            toolbarFooter: [
                {
                    item: '<button class="..." type="button"><span class="..."></span></button>',
                    event: 'click',
                    callback: function(){ tooltip1.close() }
                },
                {
                    item: '<button class="..." type="button"><span class="..."></span></button>',
                    event: 'click',
                    callback: function(){ alert( 'Yeah! Thanks :-)' ) }
                }
            ]
        });
});
$('#tooltip_3').mouseenter( function(e){
    $('#tooltip_3')
        .jsPanel({
            tooltip: {
                position: 'bottom',
                offsetY: 17,
                mode: 'semisticky'
            },
            size: { width: 555, height: 426 },
            title: 'Tooltip semisticky',
            content: '<img src="images/Hintere-Schwaerze.jpg" alt="">'
        });
});
$('#tooltip_4').mouseenter( function(e){
    $('#tooltip_4')
        .jsPanel({
            tooltip: {
                position: 'right',
                offsetX: 4
            },
            size: { width: 198, height: 98 },
            header: false,
            content: '<div class="alert alert-info"><p style="text-align:center;">Completely without
header or toolbars</p></div>' }); });
$('#tooltipmouseover_1').mouseenter( function(e){
    $('#tooltipmouseover_1')
        .jsPanel({
            tooltip: {
                position: 'top',
                offsetX: 4
            },
            id: 'tooltip_mo',
            size: { width: 240, height: 48 },
            header: false,
            content: '<p style="text-align:center;">That\'s more like a classic tooltip</p>'
        },
        function ( jsPanel ) {
            $( '.jsPanel-content', jsPanel ).css( 'background-color', '#dedede' );
            jsPanel.css({ 'border-radius':'4px', 'border':'1px solid #ababab' });
        }
    );
});

CSS3 only tooltips

If you simply need text-only tooltips jsPanel.css includes some css rules to generate a tooltip using only css3 as published by C. Bavota. See examples below:

HTML code for the examples above:

<a href="#" class="left-tip" data-tips="Tooltip left">CSS3 Tooltip left</a>
<a href="#" class="top-tip" data-tips="http://cbavota.bitbucket.org/css3-tips/">CSS3 Tooltip top</a>
<a href="#" class="bottom-tip" data-tips="http://jspanel.de/ ... by S. Sträßer">CSS3 Tooltip bottom</a>
<a href="#" class="right-tip" data-tips="Tooltip right">CSS3 Tooltip right</a>

Properties

content

version 1.11

The content property of the jsPanel represents the complete content within the jsPanel content area.

content provides easy access to the panel content in order to add/remove/replace/alter content of the jsPanel.

Examples:

var myPanel = $( 'body' ).jsPanel({ /* jsPanel config */ });

// Example 1 append a new paragraph
myPanel.content.append( '<p style="...">New paragraph ...</p>' );

// Example 2 appends a new item to the ul
$( 'ul', myPanel.content ).append( '<li>New Item</li>' );

// Example 3 removes the second paragraph
$( 'p:eq(1)', myPanel.content ).remove();

// Example 4 replaces the first paragraph
$( 'p:eq(0)', myPanel.content ).replaceWith( '<p>Property content provides access to ...</p>' );

// Example 5 removes all content from the jsPanel
myPanel.content.empty();
                            
// Example 6 inserts a new list item after Item 2
$( 'ul li:eq(1)', myPanel.content ).after( '<li>New Item 2a</li>' );

// Example 7 changes font color of the list items
$( 'ul li', myPanel.content ).css( 'color', 'red' );
and wait a moment for the content to load

The examples above show only a few possibilities how to use the property content. You can use all jQuery methods that can be chained to a jQuery object.

Methods

.addToolbar( content )

version 1.0 | last update 1.6

Adds a header toolbar to an already existing jsPanel in the same way the option.toolbarContent does and returns the jsPanel.

Internally this option uses jQuerys .append() method and thus accepts the same values as jQuerys .append() method does.

For detailed information about .append() refer to the jQuery API

var jspanel = $('#method-addtoolbar').jsPanel({
    title: 'Title of the jsPanel'
});

console.log( jspanel.addToolbar( '<img src="images/printer.png"> more toolbar content ...' ) );

.close()

version 1.0

Removes the jsPanel from the DOM and returns the the element that contained the jsPanel.

var jspanel = $( '#method-close' ).jsPanel({
    position: 'center', theme: 'medium', overflow: 'hidden',
    size: { width: 350, height: 180 }
});

window.setTimeout( function(){
    console.log( jspanel.close() );
}, 3000 );
and wait a few seconds for the animation to complete

.closeChildpanels()

version 1.0

Removes all childpanels of a jsPanel from the DOM and returns the jsPanel the childpanels were removed from.

// create a parent panel and store it in a variable
var testpanel = $( "#method-closechildpanels" ).jsPanel({
    id: 'jspanel', theme: 'primary',
    position: 'center'
});
// create a childpanel within the content area of testpanel
$( ".jsPanel-content", testpanel )
    .jsPanel({
        position: 'center', theme: 'danger', size: { width: 250, height: 150 }
    });
// remove the childpanel
window.setTimeout( function(){
    console.log( testpanel.closeChildpanels() );
}, 3000 );
and wait a few seconds for the animation to complete

.front()

version 1.3

Moves a jsPanels to the front by increasing the z-index and returns the jsPanel.

// create a few jsPanels
    var testpanel1 = $( "#method-front" ).jsPanel().css( 'background', '#5d75d7' ),
        testpanel2 = $( "#method-front" ).jsPanel(),
        testpanel3 = $( "#method-front" ).jsPanel();
// move testpanel1 to the front
window.setTimeout( function(){
    console.log( testpanel1.front() );
}, 3000 );
and wait a few seconds for the animation to complete

.maximize()

version 1.0 | last update 1.5

Maximizes or normalizes a jsPanels depending of the current status of the jsPanel and returns the jsPanel.

A normalized jsPanel (meaning it's visible at it's specified position and with it's specified size) will be maximized within its parent element.

A minimized or maximized jsPanel will be restored to its latest normalized status.

The default behaviour of jsPanels appended to the <body> element can be changed using option.restoreTo

// create a jsPanel with a childpanel
var parentpanel = $( "#method-maximize" ).jsPanel({overflow:'hidden'}),
    childpanel = $( ".jsPanel-content", parentpanel ).jsPanel({
                    size: { width: 200, height: 120 },
                    overflow:'hidden', theme:'success'
                 });
// execute the maximize method on the childpanel several times
window.setTimeout( function(){ console.log( childpanel.maximize() ); }, 2000 );
window.setTimeout( function(){ console.log( childpanel.maximize() ); }, 4000 );
window.setTimeout( function(){ console.log( childpanel.minimize() ); }, 6000 );
window.setTimeout( function(){ console.log( childpanel.maximize() ); }, 8000 );
window.setTimeout( function(){ console.log( parentpanel.maximize() ); }, 10000 );
and wait a few seconds for the animation to complete

A jsPanel appended directly to the <body> element ...
will be maximized within the window and not within the body element.

$('body').jsPanel({
    position: 'top left', theme: 'info', controls: { iconfont: 'bootstrap' },
    size: { width: 400, height: 220 }
});

.minimize()

version 1.0

Minimizes a jsPanel to the lower left corner of the browser viewport.

// create a few jsPanels
var testpanel1 = $( "#method-minimize" ).jsPanel({theme:'primary'}),
    testpanel2 = $( "#method-minimize" ).jsPanel({theme:'success'}),
    testpanel3 = $( "#method-minimize" ).jsPanel({theme:'warning'});
// minimize testpanel1
window.setTimeout( function(){
    console.log( testpanel1.minimize() );
}, 3000 );
// and minimize the other jsPanels ...
and wait a few seconds for the animation to complete

.title( [ true | string ] )

version 1.0

.title()

Returns the html element containing the title text when used without an argument

var jspanel = $('#method-title').jsPanel({
    title: 'Title of the jsPanel',
    position: 'center'
});

console.log( jspanel.title() );

.title( true )

Returns the title text when used with one argument which is true

var jspanel = $('#method-title').jsPanel({
    title: 'Title of the jsPanel',
    position: 'center'
});

console.log( jspanel.title( true ) );

.title( 'string' )

Sets the title to 'string' when used with one argument which is a string and returns the jsPanel

var jspanel = $('#method-title').jsPanel({
    title: 'Title of jspanel',
    position: 'bottom center'
});
window.setTimeout( function(){
    console.log( jspanel.title( 'And this is a new title!' ) );
}, 2000 )

Events

onjspanelloaded

version 1.6

The onjspanelloaded event is triggered when the jsPanel is appended to the document and the entry animation completed - meaning the jsPanel is fully visible.

Any handler for this event receives the event object and the ID attribut of the jsPanel as arguments.

var panel = $( '#event-onjspanelloaded' ).jsPanel({
    id: "testpanel_event_1"
});

panel.on( "onjspanelloaded", function( event, id ){
    if( id == "testpanel_event_1" )
    {
        alert( event.type + ' observed on element id: ' + id );
    }
});

onjspanelclosed

version 1.6

The onjspanelclosed event is triggered when the jsPanel is removed from the document.

Any handler for this event receives the event object and the ID attribut of the jsPanel as arguments.

Important! The handler for the "onjspanelclosed" event has to be attached to the body element.

var panel_2 = $( '#event-onjspanelclosed' ).jsPanel({
    id: "testpanel_event_2"
});

$( "body" ).on( "onjspanelclosed", function( event, id ){
    if( id == "testpanel_event_2" )
    {
        alert( event.type + ' observed on element id: ' + id );
    }
});

Callback

callback( jsPanel )

version 1.0

A callback function that is executed when the jsPanel is inserted in the document. The function receives the jsPanel as argument.

$( '#callback-callback' ).jsPanel({
    size: { width: 'auto' },
    theme: 'primary'
}, function( panel ){
    panel
        .title( 'Callback example' )
        .find( '.jsPanel-content' )
        .load( 'files/loremipsum.html' );
});

Defaults

defaults

version 1.0 | last update 1.6

A standard jsPanel without a specific configuration is created with a default value for all available options. When you specify a setting in the options object of a jsPanel the respective default value will be replaced by your setting while retaining all the other default settings.

The defaults object is shown below.

$.fn.jsPanel.defaults = {
    "ajax":          false,
    "autoclose":     false,
    "content":       false,
    "controls":      {
                         buttons:  true,
                         iconfont: false
                     },
    "draggable":     {
                         handle:  'div.jsPanel-hdr, div.jsPanel-ftr',
                         stack:   '.jsPanel',
                         opacity: 0.6
                     },
    "header":        true,
    "id":            function(){
                         $(this).first().uniqueId()
                     },
    "load":          false,
    "modal":         false,
    "overflow":      'hidden',
    "position":      'auto',
    "resizable":     {
                         handles:   'e, s, w, se, sw',
                         autoHide:  false,
                         minWidth:  150,
                         minHeight: 93
                     },
    "restoreTo":     false,
    "rtl":           {
                         rtl: false
                     },
    "show":          'fadeIn',
    "size":          {
                         width:  400,
                         height: 222
                     },
    "statusbar":     false,
    "theme":         'light',
    "title":         function(){
                         return 'jsPanel No ' + ( $('.jsPanel').length + 1 )
                     },
    "toolbarFooter": false,
    "toolbarHeader": false,
    "tooltip":       false
};

How to change defaults globally

To change defaults globally you have to edit the defaults object prior creating a jsPanel. If you want to make the bootstrap iconfonts the default for every jsPanel you create you would have to put the following code in your script prior a call to .jsPanel()

$.fn.jsPanel.defaults.controls.iconfont = 'bootstrap';

To change the default theme globally ...

$.fn.jsPanel.defaults.theme = 'primary';