jsPanel Documentation
On this page:

option.selector

With option.selector you define where in the DOM you want to place the jsPanel.

Type: jQuery Selector
option.selector expects a jQuery Selector as value. Although a jquery selector can represent a collection of elements a jsPanel will be appended only to the first element in the collection.

Default: "body"
So in order to append a jsPanel to the body element of your document you don't need to set option.selector.

selector omitted 
$.jsPanel({
    // selector omitted
    title: "selector omitted",
    theme: "light"
});
Execute example 1
selector used 
$.jsPanel({
    selector: "#panel1",
    title:    "selector used with element id",
    theme:    "light"
});
Execute example 2

Since both examples don't use any further positioning the jsPanels are positioned at the top left corner of the element containing the jsPanel. If you click the buttons repeatedly you'll see that every new jsPanel within the same container will be offset by a few pixels.

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 other than the body element that is not positioned accordingly.

Notes:
  • For standard and extended modal jsPanels option.selector is set to body. Other values are ignored!
  • If the element referenced with option.selector doesn't exsist, an error message is logged to the console.
  • jsPanel behaviour on page scroll:
    • jsPanels appended to the body element will maintain their position relative to the top left corner of the browser viewport jsPanels will remain in the viewport unless you deliberately positioned them off screen
    • jsPanels appended to other elements will maintain their position relative to the top left corner of their container element jsPanels will scroll out of view with the page

option.position

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"

Valid string values are:

"auto" | "center" | "top left" | "top center" | "top right" | "center right", "bottom right" | "bottom center" | "bottom left" | "center left" and don't need any further explanation. Note that there has to be exactly one space in between the two-word-combinations.

$.jsPanel({
    position: "center"
});
Execute example 3 
$.jsPanel({
    position: "center right"
});
Execute example 4 
$.jsPanel({
    position: "bottom left"
});
Execute example 5

"center" options in combination with size.width and/or size.height set to "auto"
To center the jsPanel properly the width and/or height 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 an object

When using an object as value for option.position a feasible combination of two keys out of the following 4 options is expected: top:, left:, bottom:, right:

And each of the keys top:, left:, bottom:, right: expects one of the following values:

  • integer will be used as pixel value
  • string "auto" will result in automatic positioning within the container the jsPanel is appended to.
  • string "center" will center the jsPanel horizontally, vertically or both
  • any other string will will be parsed using parseInt() and the result will be used as pixel value
  • function(jsPanel) The return value of the function should be usable as value for the css positioning. The function receives the jsPanel as argument
$.jsPanel({
    position: {
        top: 300,
        left: 300
    }
});
// no selector -> body element
Execute example 6 
$.jsPanel({
    position: {
        top: '350px',
        left: 350
    }
});
// no selector -> body element
Execute example 7 
$.jsPanel({
    position: {
        top: 400,
        left: "center"
    }
});
// no selector -> body element
Execute example 8 
$.jsPanel({
    selector: "#panel3",
    position: {
        bottom: "auto",
        right: "auto"
    }
});
// click repeatedly to see the
// effect of automatic positioning
Execute example 9 
$.jsPanel({
    selector: "#panel3",
    position: {
        bottom: 50,
        right: 50
    }
});
// compare this with the next
// example without selector
Execute example 10 
$.jsPanel({
    position: {
        bottom: 50,
        right: 50
    },
    theme: "autumngreen",
    callback: function(panel){ /* */ }
});
// no selector -> body element
Execute example 11 
$.jsPanel({
    size: { width: 400, height: 246 },
    position: {
        top: function(panel){
            return ( $(window).height() / 2 ) - ( parseInt(panel.css('height')) / 2 );
        },
        left: function(panel){
            return ( $(window).width() / 2 ) - ( parseInt(panel.css('width')) / 2 );
        }
    }
});

Example 12 uses functions to calculate position values and shows an alternative way to center a jsPanel within the body element. Note that the functions receive the jsPanel as argument.

Execute example 12

option.offset

option.offset sets horizontal and/or vertical position offsets. Passed values are simply added to the respective values of option.position.

Type: object Default: { top: 0, left: 0 } values for top & left have to be integers

Example 13 appends 2 jsPanels to the body element and positions both using option.position with a value of "center". This would normally result in 2 panels piled up on each other at the center position of the window. With option.offset one panel is moved left and the other one is moved right resulting in both panels centered side by side.

$.jsPanel({
    position: 'center',
    offset:   { top: 0, left: -202 },      // moved left by half panel width plus 2 pixels spacing
    size:     { width: 400, height: 222 }, // it should be clear that panel width has to be known
    theme:    'autumngreen',
    content:  "<img src='http://placehold.it/400x222&text=left panel' alt=''>"
});
$.jsPanel({
    position: 'center',
    offset:   { top: 0, left: 202 },       // moved right by half panel width plus 2 pixels spacing
    size:     { width: 400, height: 222 }, // it should be clear that panel width has to be known
    theme:    'autumnred',
    content:  "<img src='http://placehold.it/400x222&text=left panel' alt=''>"
});
Execute example 13

Example 14 is basically the same as example 13 with a vertical setup. Don't forget here that option.size.height sets content height, not panel height. So the vertical offset has to be adjusted accordingly.

$.jsPanel({
    position: 'center',
    offset:   { top: -129, left: 0 },      // moved up by approximately half panel height
    size:     { width: 400, height: 222 }, // it should be clear that panel height has to be known
    theme:    'autumngreen',
    content:  "<img src='http://placehold.it/400x222&text=upper panel' alt=''>"
});
$.jsPanel({
    position: 'center',
    offset:   { top: 129, left: 0 },       // moved down by approximately half panel height
    size:     { width: 400, height: 222 }, // it should be clear that panel height has to be known
    theme:    'autumnred',
    content:  "<img src='http://placehold.it/400x222&text=lower panel' alt=''>"
});
Execute example 14

Example 15 is a combination of the previous two examples and groups four jsPanels.

$.jsPanel({
    position: "center",
    offset:   { top: -129, left: -202 },
    size:     { width: 400, height: 222 },
    theme:    "autumngreen",
    content:  "<img src='placehold.it/400x222&text=upper left'>"
});

$.jsPanel({
    position: "center",
    offset:   { top: -129, left: 202 },
    size:     { width: 400, height: 222 },
    theme:    "autumnred",
    content:  "<img src='placehold.it/400x222&text=upper right'>"
});

$.jsPanel({
    position: "center",
    offset:   { top: 129, left: -202 },
    size:     { width: 400, height: 222 },
    theme:    "autumnbrown",
    content:  "<img src='placehold.it/400x222&text=lower left'>"
});

$.jsPanel({
    position: "center",
    offset:   { top: 129, left: 202 },
    size:     { width: 400, height: 222 },
    theme:    "dark",
    content:  "<img src='placehold.it/400x222&text=lower right'>"
});
Execute example 15

Positioning modal jsPanels

Standard modals
  • option.selector is always set to "body". Other settings are ignored!
  • option.position is always set to "center". Other settings are ignored!
  • option.offset is always set to { top: 0, left: 0 }. Other settings are ignored!

In short: standard modals are always appended to the body element and centered within the browser viewport.

Extended modals
  • option.selector is always set to "body". Other settings are ignored!
  • The other positioning options are not limited.

Positioning tooltips

  • option.selector defines the element that triggers the tooltip on mouseover
  • option.position is ignored. The position of the tooltip is set in the configuration object option.paneltype. Tooltip positions are limited to top, right, bottom and left
  • option.offset is available without limitations and almost always necessary to fine tune tooltip position
  • option.shiftwithin By default a tooltip checks whether its boundaries overflow the browser viewport. If so top and bottom tooltips shift either left or right depending on which side they overflow. Left and right tooltips shift either up or down depending on which side they overflow.
    With this parameter you can set another element as reference the tooltip should shift within in case it overflows. This is useful when you have a tooltip within a container whose overflow property is set to hidden. Click for an example or see the tooltip example within the jsPanel on the jsPanel home page.

Positioning hints

All three positioning options option.selector, option.position and option.offset work without limitations as described above. But note the particularity of option.position:

When - and only when! - you create hints using option.position with one of the shortcut values "top left", "top center" or "top right" hints are prevented from piling up on each other and remaining hints reposition upon closing of a hint.

method reposition(position [, selector])

The method reposition(position [, selector]) allows to reposition an exsisting jsPanel. The parameter position accepts the same values as option.position.

The optional parameter selector allows to simultaneously move an exsisting jsPanel from one containing element to another container and expects a jQuery selector string.

var panel17 = $.jsPanel({
    selector: "#panel4",
    position: "center",
    size:     {width:250,height:120},
    theme:    "autumngreen"
});
window.setTimeout(function(){
    panel17.reposition("center left");
},2000);
Execute example 17 
var panel18 = $.jsPanel({
    selector: "#panel4",
    position: "top center",
    size:     {width:250,height:120},
    theme:    "autumnbrown"
});
window.setTimeout(function(){
    panel18.reposition({top:10,right:10});
},2000);
Execute example 18 
var panel19 = $.jsPanel({
    selector: "#panel4",
    position: {top:20,left:20},
    size:     {width:250,height:120},
    theme:    "autumnred"
});
window.setTimeout(function(){
    panel19.reposition("auto", "body");
    // note additional argument to
    // move the panel to another
    // container
},2000);
Execute example 19