Getting Started

Required

  • jQuery 1.7.0 or above.
  • jQuery UI Core 1.8.6 or above.
    jQuery UI Core consists of the following components: Core, Widget, Mouse and Position. No other jQuery UI components are required.

Optional

  • Velocity.js 1.0.0 or above.
    If the Velocity.js animation library is loaded, ProPanelLayout will automatically enable animation support.
  • ProDraggable* 0.1.0 or above.
    If the ProDraggable widget is loaded, drag resizing of panels will be available.
    * ProDraggable is currently in beta. It's feature set is limited to that required by ProPanelLayout, therefore its public API is subject to change without notice.

Browser Support

Instead of targeting an ever increasing plethora of specific browsers we simply craft thoroughly designed, meticulously developed products using the latest standards, best practices and progressive enhancements. Our products work best with modern browsers, but will accommodate older browsers to the most practical extent possible.

ProPanelLayout uses the following modern features when available:

Installation

Add ProPanelLayout source files to your page:

<link rel="stylesheet" href="/propanellayout-1.0.x/css/propanellayout.css">
<script src="/propanellayout-1.0.x/js/propanellayout.js"></script>

ProPanelLayout is now ready to use. If you are using a theme other than "silvercore" be sure to load your custom CSS too.

Usage

ProPanelLayout consists of three specialised widgets:

  • ProPanelLayout
    The ProPanelLayout widget is the layout manager. It creates ProCenterPanel and ProOuterPanel widgets and manages their state by setting their options and reacting to their events.
  • ProCenterPanel
    The ProCenterPanel widget exposes an API for ProPanelLayout center panels. Multiple center panels can be added to a layout, although only one center panel may be active. The center panel minWidth and minHeight options drive layout responsiveness by forcing ProOuterPanel widgets to reduce their size or change state.
  • ProOuterPanel
    The ProOuterPanel widget exposes an API for ProPanelLayout north, south, east and west panels. Multiple panels of any type can be added to any layout. Outer panels are responsible for almost all of the ProPanelLayout user interface.

A panel layout can be created from any container element body, div etc. and needs a small amount of configuration to get started. As a minimum at least one center panel should be defined. Adding a center panel can be done on initialisation using the center option or after initialisation by using the addPanel() method. If your layout configuration is complex and consists of many nested layouts and multiple panels you might find it easier and more convenient to build your layout modularly using the addPanel() and addLayout() methods rather than trying to manage a huge nested options object.

If your main layout container is required to be full screen, as is typical for web applications, then you should set viewport: true on the root layout widget. This will apply a fixed position and hook the layout dimensions to the viewport width and height which enables your entire layout to respond to the available space with optimised performance through caching. If you initialise a layout with viewport: false that is not a nested layout, you must apply the container width and height by other means and use the updateLayout() method when appropriate to synchronise the widget dimensions with the actual CSS width and height.

Adding north, south, east and west panels, like center panels, can be done on initialisation using the north, south, east, west or panel options, or by using the addPanel() method. Panel elements must be existing elements in your HTML source. Multiple panels of any type can be added using an array of panel options objects.

ProPanelLayout will manipulate the DOM to create any possible layout - there is no special requirement regarding the source HTML hierarchy. Elements can originate anywhere within the DOM, even inside sibling panels, and will be moved to an appropriate parent element on initialisation. Placeholder elements are used as needed to restore the original DOM structure when a widget collapses or is destroyed. This automatic restructuring is invaluable when creating responsive layouts, as secondary content can be contained within panels when enough space is available but moved back to its original location when the panel collapses.

Since exact configuration depends on your source HTML the following example code should only be used as a guide to understanding the two main initialisation methods. Use the documentation and demos to get started with the method that best suits your project.

// Initialise a complex nested layout using nested options
$("#element").proPanelLayout({
    viewport: true,
    // Using named panel options
    center: {
        element: "#center",
        layout: {
            type: "proPanelLayout", // Default type, more ProLayout widgets are coming!
            center: {
                element: "#nested-center"
            },
            north: {
                element: "#nested-north"
            }
        }
    },
    north: {
        element: "#north"
    },
    west: {
        element: "#west"
    },
    // Using the generic "panel" option to initialise "south" and "east" panels using an array of panel options
    panel: [
    {
        element: "#south",
        type: "south"        
    },
    {
        element: "#east",
        type: "east",       
    }
    ]
});

// Initialise the same complex nested layout as above using modular initialisation and method chaining
$("#element")
    .proPanelLayout({
        viewport: true
    })
    // Add the center panel using the element and type properties
    .proPanelLayout("addPanel", {
        element: "#center",
        type: "center"
    })
    // Add the north panel using the element property and the type argument
    .proPanelLayout("addPanel", {   
        element: "#north"
    }, "north")
    // Add the west panel using the element property and the type argument
    .proPanelLayout("addPanel", {
        element: "#west"
    }, "west")
    // Add multiple panels using an array of panel options objects
    .proPanelLayout("addPanel", [
        {
            element: "#south",
            type: "south"            
        },
        {
            element: "#east",
            type: "east",       
        }
    ]);

    // Add the nested layout to the center panel using a nested options object and the layout type argument
    $("#center").proCenterPanel("addLayout", {
        center: {
            element: "#nested-center"
        },
        north: {
            element: "#nested-north"
        }
    }, "proPanelLayout");

ProPanelLayout

The ProPanelLayout widget is the layout manager. It creates ProCenterPanel and ProOuterPanel widgets and manages their state by setting their options and reacting to their events.

Options

Options are used to configure the widget and can be set on initialisation by passing an options object to the widget plugin, or after initialisation by using the option() method.

center

Type: Object Default: null

Adds a center panel to the layout by initialising a ProCenterPanel widget. The element property is required and must be of type Selector, Element or jQuery. All other properties are passed directly to the ProCenterPanel plugin on initialisation.

$("#element").proPanelLayout({
    center: {
        element: "#center",
        minWidth: 400,
        minHeight: 300
    }
});

centerPanelOptions

Type: Object Default: {}

Defines panel options applied to all ProCenterPanel widgets initialised by the layout. centerPanelOptions are only applied to new panels created with the center and panel options, or created with the addPanel() method. centerPanelOptions are not applied to existing panels added to the layout using the addPanel() method.

This option is useful for setting common panel options and reduces repetition in the initialisation options.

$("#element").proPanelLayout({
    centerPanelOptions: {
        minWidth: 400,
        minHeight: 300
    }
});

debug

Type: Boolean Default: false

Enables debug mode. In debug mode errors and warnings are output to the console.

$("#element").proPanelLayout({
    debug: true
});

east

Type: Object | Array Default: null

Adds an east (right side) panel to the layout by initialising a ProOuterPanel widget with type: "east". The element property is required and must be of type Selector, Element or jQuery. All other properties are passed directly to the ProOuterPanel plugin on initialisation. Passing an array of objects will initialise multiple panels.

$("#element").proPanelLayout({
    east: {
        element: "#east",
        state: "open",
        size: 400,
        minSize: 200,
        maxSize: 500,
        allowResize: true
    }
});

$("#element").proPanelLayout({
    east: [
        {
            element: "#east-1",
            state: "open",
            size: 400,
            minSize: 200,
            maxSize: 500,
            allowResize: true
        },
        {
            element: "#east-2",
            state: "inactive",
            size: 200
        }
    ]
});

formation

Type: String Default: "standard"

Defines the formation of the north, south, east and west panels within the layout.

  • "standard" – the north and south panels fill the entire width of the layout.
  • "alternative" – the east and west panels fill the entire height of the layout.
$("#element").proPanelLayout({
    formation: "alternative"
});

north

Type: Object | Array Default: null

Adds a north (header) panel to the layout by initialising a ProOuterPanel widget with type: "north". The element property is required and must be of type Selector, Element or jQuery. All other properties are passed directly to the ProOuterPanel plugin on initialisation. Passing an array of objects will initialise multiple panels.

$("#element").proPanelLayout({
    north: {
        element: "#north",
        state: "open",
        size: 400,
        minSize: 200,
        maxSize: 500,
        allowResize: true
    }
});

$("#element").proPanelLayout({
    north: [
        {
            element: "#north-1",
            state: "open",
            size: 400,
            minSize: 200,
            maxSize: 500,
            allowResize: true
        },
        {
            element: "#north-2",
            state: "inactive",
            size: 200
        }
    ]
});

outerPanelOptions

Type: Object Default: {}

Defines panel options applied to all ProOuterPanel widgets initialised by the layout. outerPanelOptions are only applied to new panels created with the north, south, east, west and panel options, or created with the addPanel() method. outerPanelOptions are not applied to existing panels added to the layout using the addPanel() method.

This option is useful for setting common panel options and reduces repetition in the initialisation options.

$("#element").proPanelLayout({
    outerPanelOptions: {
        minWidth: 400,
        minHeight: 300
    }
});

overlayOpacity

Type: Number Default: 0.65

Defines the opacity of the overlay used for sliding panels with modal: true. The value must be between 0 and 1 inclusive.

$("#element").proPanelLayout({
    overlayOpacity: 0.3
});

panel

Type: Object | Array Default: null

Adds a panel to the layout by initialising a ProCenterPanel or ProOuterPanel widget as appropriate. If type is omitted the a ProCenterPanel widget is created. The element property is required and must be of type Selector, Element or jQuery. All other properties are passed directly to the ProCenterPanel or ProOuterPanel plugin on initialisation. Passing an array of objects will initialise multiple panels.

This is a generic panel initialiser and can be used as a replacement for, or along with, the north, south, east, west and center options. Panels defined by the panel option are initialised before panels defined by other options.

$("#element").proPanelLayout({
    panel: {
        element: "#east",
        type: "east",
        state: "open",
        size: 400,
        minSize: 200,
        maxSize: 500,
        allowResize: true
    }
});

$("#element").proPanelLayout({
    panel: [
        {
            element: "#east",
            type: "east",
            state: "open",
            size: 400,
            minSize: 200,
            maxSize: 500,
            allowResize: true
        },
        {
            element: "#west",
            type: "west",
            size: 200
        }
    ]
});

priorityEW

Type: String Default: "west"

Defines which panel has priority when the layout has active east and west panels. The value must be one of "east", "west", "e" or "w" and is case insensitive. Priority applies to the following scenarios:

Responsive layout
When the responsiveSize and responsiveState options are enabled for east and west panels, priorityEW determines the order in which panels are resized and closed. E.g. when priorityEW: "east" the west panel will resize and close before the east panel.
Sliding panels
When both east and west panels are sliding (assuming neither are modal) and the panel sizes cause both panels to overlap, priorityEW determines which panel appears on top (by setting a higher zIndex).
Getting panels
When getting active panels using the panels() method, if both east and west panels are requested priorityEW determines the order in which the panels are returned.

$("#element").proPanelLayout({
    priorityEW: "east"
});

$("#element").proPanelLayout({
    priorityEW: "E" // Shorthand
});

priorityNS

Type: String Default: "north"

Defines which panel has priority when the layout has active north and south panels. The value must be one of "north", "south", "n" or "s" and is case insensitive. Priority applies to the following scenarios:

Responsive layout
When the responsiveSize and responsiveState options are enabled for north and south panels, priorityNS determines the order in which panels are resized and closed. E.g. when priorityEW: "south" the north panel will resize and close before the south panel will resize and close.
Sliding panels
When both north and south panels are sliding (assuming neither are modal) and the panel sizes cause both panels to overlap, priorityNS determines which panel appears on top (by setting a higher zIndex).
Getting panels
When getting active panels using the panels() method, if both north and south panels are requested priorityNS determines the order in which the panels are returned.

$("#element").proPanelLayout({
    priorityNS: "south"
});

$("#element").proPanelLayout({
    priorityNS: "S" // Shorthand
});

south

Type: Object | Array Default: null

Adds a south (footer) panel to the layout by initialising a ProOuterPanel widget with type: "south". The element property is required and must be of type Selector, Element or jQuery. All other properties are passed directly to the ProOuterPanel plugin on initialisation. Passing an array of objects will initialise multiple panels.

$("#element").proPanelLayout({
    south: {
        element: "#south",
        state: "open",
        size: 400,
        minSize: 200,
        maxSize: 500,
        allowResize: true
    }
});

$("#element").proPanelLayout({
    south: [
        {
            element: "#south-1",
            state: "open",
            size: 400,
            minSize: 200,
            maxSize: 500,
            allowResize: true
        },
        {
            element: "#south-2",
            size: 200
        }
    ]
});

theme

Type: String Default: "silvercore"

Defines the theme class applied to the widget and overlay element. The theme class is the string "pro-panel-layout--theme-value". For this option to have any effect, related CSS styles that make use of the theme class must be present. Setting the widget theme using this option enables multiple themes to be loaded at once and applied to individual ProPanelLayout instances independently of each other, or even for themes to be switched after initialisation.

$("#element").proPanelLayout({
    theme: "my-theme" // Creates a class of "pro-panel-layout--theme-my-theme"
});

viewport

Type: Boolean Default: false

Defines the layout to be a viewport. A viewport layout uses a fixed position to fill the entire viewport. In addition, an event handler is bound to the window resize event to relay the current viewport width and height to the widget so that the layout can be updated and panel state set appropriately. This option is most appropriate for web applications.

$("#element").proPanelLayout({
    viewport: true
});

west

Type: Object | Array Default: null

Adds a west (left side) panel to the layout by initialising a ProOuterPanel widget with type: "west". The element property is required and must be of type Selector, Element or jQuery. All other properties are passed directly to the ProOuterPanel plugin on initialisation. Passing an array of objects will initialise multiple panels.

$("#element").proPanelLayout({
    west: {
        element: "#west",
        state: "open",
        size: 400,
        minSize: 200,
        maxSize: 500,
        allowResize: true
    }
});

$("#element").proPanelLayout({
    west: [
        {
            element: "#west-1",
            state: "open",
            size: 400,
            minSize: 200,
            maxSize: 500,
            allowResize: true
        },
        {
            element: "#west-2",
            size: 200
        }
    ]
});

zIndex

Type: Number Default: 10

Defines the base zIndex value. The stacking order of panels within the layout is fully managed by the widget. Panel zIndex values are calculated based on many factors including priority, state, modality and animation. Overriding panel zIndex manually is not recommended. Use this option only to increase the base zIndex from which the stacking order is begun.

Essentially, any element within the layout container that is not a panel will be hidden beneath all panels if it has a zIndex value lower than the value set.

$("#element").proPanelLayout({
    zIndex: 10000
});

Methods

Widget methods are invoked by passing the method name to the jQuery plugin:

$("#element").widget("method")

If a method accepts arguments they can be passed after the method name:

$("#element").widget("method", 10)

Most methods return the jQuery object for chaining:

$("#element").widget("method").show()

However, some methods might return a value:

var value = $("#element").widget("method") // 10

addPanel(panel[, panelType])

Adds one or more panels to the layout. If type is omitted from the panel options the panelType argument should be used. If the type is not defined a ProCenterPanel will be created.

If an active panel is added to a layout with an existing active panel of the same type, the existing panel will be deactivated and the added panel will become the active panel.

In addition to the documented options for ProCenterPanel and ProOuterPanel widgets the panel options object must include an element property used to target the widget element.

Arguments

panel
Type: Object | Array | ProCenterPanel | ProOuterPanel
A ProCenterPanel or ProOuterPanel options object, an array of ProCenterPanel or ProOuterPanel options objects, a ProCenterPanel or ProOuterPanel widget. When passing a ProOuterPanel widget the panelType argument can be used to override the existing type.
panelType
Type: String
For panels of type "center", or if the panel type is not defined, a ProCenterPanel widget will be created. For panels of type "north", "south", "east", "west" a ProOuterPanel widget will be created.

Return

Type: jQuery
The widget element for chaining.

// Add a west panel
$("#element").proPanelLayout("addPanel", {
    element: "#west",
    type: "west",
    size: 240
});
// Add a west panel
$("#element").proPanelLayout("addPanel", {
    element: "#west",
    size: 240
}, "west");
// Add multiple panels of mixed types
$("#element").proPanelLayout("addPanel", [
    {
        element: "#center",
        type: "center",
        minWidth: 500
    }
    {
        element: "#west",
        type: "west",
        state: "closed",
        size: 240
    }
]);
// Add an existing panel from another layout and change the type
// Assumes "#west" has already been initialised as a ProOuterPanel
$("#element").proPanelLayout("addPanel", $("#west"), "north");
// ... alternative syntax
$("#element").proPanelLayout("addPanel", {element: "#west"}, "north");
);

center()

Gets the active center panel.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The active center panel.

$("#element").proPanelLayout("center")

destroy()

Destroys the widget along with all associated data, elements and bindings. Restores the widget element to its pre-widget state. All panels associated with the layout will also be destroyed along with any nested layouts belonging to those panels an so on. Therefore the destruction of an entire hierarchical layout can be achieved by destroying the root widget.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proPanelLayout("destroy")

east()

Gets the active east panel.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The active east panel.

$("#element").proPanelLayout("east")

flip()

Toggles the formation option between "standard" and "alternative".

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proPanelLayout("flip")

north()

Gets the active north panel.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The active north panel.

$("#element").proPanelLayout("north")

option()

Gets the values of all options.

Arguments

This method does not accept any arguments

Return

Type: Object
An object containing all option values.

$("#element").proPanelLayout("option")

option(optionName)

Gets the value of a single option.

Arguments

optionName
Type: String
The option to get.

Return

Type: Any
The option value. The type depends on the option.

$("#element").proPanelLayout("option", "enabled")

option(options)

Sets multiple options.

Arguments

options
Type: Object
A map of option-value pairs.

Return

Type: jQuery
The widget element for chaining.

$("#element").proPanelLayout("option", {
    disabled: true
})

option(optionName, value)

Sets a single option.

Arguments

optionName
Type: String
The option to set.
value
Type: Any
The value to set. The type depends on the option.

Return

Type: jQuery
The widget element for chaining.

$("#element").proPanelLayout("option", "disabled", true)

panels([panelType])

Gets all active panels, optionally filtered by type. If north and south or east and west panels are requested they are sorted according to the priorityNS and priorityEW options respectively.

Arguments

panelType
Type: string
Filters the returned active panels (only those requested are returned). If a value is omitted all active panels are returned. The value must be a comma separated list of panel types "north", "south", "east", "west" and "center" or a combination of the one-letter shorthand types "n", "s", "e", "w" and "c", optionally comma separated.

Return

Type: jQuery
The requested active panel elements. If there are no active panels of the requested type an empty jQuery selection is returned.

// Returns the active north and south panels, if they exist
$("#element").proPanelLayout("panels", "north, south");
// Returns the active east and center panels, if they exist
$("#element").proPanelLayout("panels", "east,center");
// Returns the active north, south, east and west panels, if they exist
$("#element").proPanelLayout("panels", "nsew");
// Returns the active west and center panels, if they exist
$("#element").proPanelLayout("panels", "west, c");

south()

Gets the active south panel.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The active south panel.

$("#element").proPanelLayout("south")

updateLayout([width[, height]])

Updates the layout based on the defined width and height. In most cases layout updating is handled automatically and you should only call the updateLayout() method if you are actively manipulating the width and height of the widget element by some other means e.g. a resizable widget, window resizing etc.

The width and height arguments supplied to the updateLayout() method are only used to configure the active panels. ProPanelLayout does not set the CSS width and height properties of the widget element - these values must be applied externally!

If you are manually calling this method you should always provide cached width and height values to avoid layout thrashing.

Arguments

width
Type: Number
The width to be used to calculate the layout. If omitted the widget element clientWidth is used.
height
Type: Number
The height to be used to calculate the layout. If omitted the widget element clientHeight is used.

Return

Type: Object
The widget element for chaining.

$("#element").proPanelLayout("updateLayout", 640, 480)

west()

Gets the active west panel.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The active west panel.

$("#element").proPanelLayout("west")

ProCenterPanel

The ProCenterPanel widget exposes an API for ProPanelLayout center panels. Multiple center panels can be added to a layout, although only one center panel may be active. The center panel minWidth and minHeight options drive layout responsiveness by forcing ProOuterPanel widgets to reduce their size or change state.

ProCenterPanel widgets should not be initialised directly; they are automatically created by the ProPanelLayout widget using the center or panel options, or the addPanel() method.

Options

Options are used to configure the widget and can be set on initialisation by passing an options object to the widget plugin, or after initialisation by using the option() method.

debug

Type: Boolean Default: false

Enables debug mode. In debug mode errors and warnings are output to the console. Additionally, the panel dimensions are output in a debug element appended to the widget element and positioned to the top left of the panel. The debug option is automatically synchronised with the layout debug option whenever a panel is added to a layout or the layout debug option is changed.

$("#element").proCenterPanel({
    debug: true
});

layout

Type: Object Default: null

Adds a nested layout to the panel by initialising a layout widget on the defined element using the passed options. The widget property can optionally be used to define the widget to be initialised, which by default is "proPanelLayout". The element property is optional and must be of type Selector, Element or jQuery. If the element property is omitted the widget element will be the layout widget element. All other properties are passed directly to the layout widget plugin on initialisation.

If the element to be initialised is not a child of the panel element, nor the panel element itself, the element will be moved to be a child of the panel element and a placeholder element will be used to restore the layout element to its original location within the DOM if the layout collapses or is destroyed.

// Intialise #element as a ProLayout widget
$("#element").proCenterPanel({
    layout: {
        widget: "proPanelLayout",
        center: {
            element: "#center",
            minWidth: 400,
            minHeight: 300
        }
    }
});

minHeight

Type: Number Default: 0

Defines the minimum height of the panel. If the layout cannot accommodate the panel at its minimum height the layout will collapse. If ProOuterPanel responsiveSize and responsiveState options are enabled for active north and south panels, the layout will automatically resize and eventually close those panels in an attempt to free up vertical space before collapsing.

$("#element").proCenterPanel({
    minHeight: 300
});

minWidth

Type: Number Default: 0

Defines the minimum width of the panel. If the layout cannot accommodate the panel at its minimum width the layout will collapse. If ProOuterPanel responsiveSize and responsiveState options are enabled for active east and west panels in the same layout, the layout will automatically resize and eventually close those panels in an attempt to free up horizontal space before collapsing.

$("#element").proCenterPanel({
    minWidth: 300
});

persist

Type: String Default: 'state'

Defines which options to persist. An empty string disables persistence. ProCenterPanel uses LocalStorage to persist widget options across page loads and automatically handles putting and getting stored options. The string must be a comma separated list of options. Any option can be persisted, but normally you should only need to persist options that can be changed through the user interface.

// Disables persistence
$("#element").proOuterPanel({
    persist: ""
});

state

Type: String Default: "active"

Defines the panel state to be one of the following:

  • "active" – the panel is the active panel, appears on top of all other center panels and its size is updated as needed.
  • "inactive" – the panel is hidden and its size is not updated.
$("#element").proCenterPanel({
    state: "active"
});

theme

Type: String Default: "silvercore"

Defines the theme class applied to the widget element. The theme class is the string "pro-panel--theme-value". For this option to have any effect, related CSS styles that make use of the theme class must be present. The theme option is automatically synchronised with layout theme option whenever a panel is added to a layout or the layout theme option changes. Setting the theme option directly on a center panel isn't recommended.

$("#element").proCenterPanel({
    theme: "my-theme" // Creates a class of "pro-panel--theme-my-theme"
});

Methods

Widget methods are invoked by passing the method name to the jQuery plugin:

$("#element").widget("method")

If a method accepts arguments they can be passed after the method name:

$("#element").widget("method", 10)

Most methods return the jQuery object for chaining:

$("#element").widget("method").show()

However, some methods might return a value:

var value = $("#element").widget("method") // 10

activate()

Sets a panel to be the active center panel.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element.

$("#element").proCenterPanel("activate");

option()

Gets the values of all options.

Arguments

This method does not accept any arguments

Return

Type: Object
An object containing all option values.

$("#element").proCenterPanel("option")

option(optionName)

Gets the value of a single option.

Arguments

optionName
Type: String
The option to get.

Return

Type: Any
The option value. The type depends on the option.

$("#element").proCenterPanel("option", "enabled")

option(options)

Sets multiple options.

Arguments

options
Type: Object
A map of option-value pairs.

Return

Type: jQuery
The widget element for chaining.

$("#element").proCenterPanel("option", {
    disabled: true
})

option(optionName, value)

Sets a single option.

Arguments

optionName
Type: String
The option to set.
value
Type: Any
The value to set. The type depends on the option.

Return

Type: jQuery
The widget element for chaining.

$("#element").proCenterPanel("option", "disabled", true)

ProOuterPanel

The ProOuterPanel widget exposes an API for ProPanelLayout north, south, east and west panels. Multiple panels of any type can be added to any layout. Outer panels are responsible for almost all of the ProPanelLayout user interface.

ProOuterPanel widgets should not be initialised directly; they are automatically created by the ProPanelLayout widget using the north, south, east, west or panel options, or the addPanel() method.

Options

Options are used to configure the widget and can be set on initialisation by passing an options object to the widget plugin, or after initialisation by using the option() method.

allowResize

Type: Boolean Default: true

Defines whether the user is able to resize the panel in the following scenarios:

  • By double clicking on the panel handle when the panel is open or sliding (resetting the panel to its initial size).
  • By dragging the panel handle (assuming all other conditions for drag resizing are met).

The allowResize option has no effect on setting the panel size using the API.

$("#element").proOuterPanel({
    allowResize: false
});

allowSlide

Type: Boolean Default: true

Defines whether the user is able to slide the panel by clicking on the panel handle when the panel is closed. The allowSlide option has no effect on setting the panel state using the API or on the toggleAction option.

$("#element").proOuterPanel({
    allowSlide: false
});

animateCenter

Type: Boolean | String | Object Default: true

Defines whether the center panel is animated for the open(), close(), slide(), hide(), peep(), deactivate() and resize() methods, assuming animation is enabled. A true or false value applies to all methods. To set the option for each method independently pass either a String of method names for which to animateCenter, or an Object mapping method names to true or false values. Methods omitted from the Object or methods without Boolean values will use the default value.

// Disables center panel animation for all methods
$("#element").proOuterPanel({
    animateCenter: false
});
// Enables the center panel animation for the open and close methods only
$("#element").proOuterPanel({
    animateCenter: "open,close"
});
// Enables center panel animation for the open and slide methods and disables center panel animation for the peep, close, hide and deactivate methods
$("#element").proOuterPanel({
    animateCenter: {
        open: true,
        slide: true,
        peep: false,
        close: false,
        hide: false,
        deactivate: false
    }
});
// Updates the open state only, assuming an object was set on initialisation
$("#element").proOuterPanel("option", "animateCenter.open", false);

autoClose

Type: Number Default: 400

Defines the delay in milliseconds before automatic closure of a sliding panel after the mouse leaves the panel/handle area. A value of 0 disables this feature.

// Allows 2 seconds before auto closing
$("#element").proOuterPanel({
    autoClose: 2000
});
// Disables autoclosing
$("#element").proOuterPanel({
    autoClose: 0
});

closedState

Type: String Default: "closed"

Defines the closed state of the panel as one of "closed", "hidden" or "peeping". Not all layout designs will use "closed" as the default closed state, however the closed state must be known in the following scenarios:

  • When calculating the center panel position in relation to a sliding panel.
  • When auto closing a panel in a responsive layout.
  • When auto closing a sliding panel.
$("#element").proOuterPanel({
    closedState: "hidden"
});

debug

Type: Boolean Default: false

Enables debug mode. In debug mode errors and warnings are output to the console. Additionally, the panel dimensions are output in a debug element appended to the widget element and positioned to the top left of the panel. The debug option is automatically synchronised with the layout debug option whenever a panel is added to a layout or the layout debug option is changed.

$("#element").proOuterPanel({
    debug: true
});

disabled

Type: Boolean Default: false

Disables all user interface controls and functionality. The disabled option has no effect on updating the widget using the API.

$("#element").proOuterPanel({
    disabled: true
});

duration

Type: Number | String | Object Default: 400

Defines the animation duration for the open(), close(), slide(), hide(), peep(), deactivate() and resize() methods, assuming animation is enabled. A Number or String value applies to all methods. To set the option for each method independently pass an Object mapping method names to Number or String values. Methods omitted from the object map or methods without Number or String values will use the default value.

Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.

// Set the duration to 250 milliseconds for all methods.
$("#element").proOuterPanel({
    duration: 250
});
// Set the duration for each method independently.
$("#element").proOuterPanel({
    duration: {
        open: "slow",
        close: "slow",
        peep: 100,
        slide: 200,
        deactivate: 0,
        hide: "normal",
        resize: "fast"
    }
});
// Updates the open state only, assuming an object was set on initialisation
$("#element").proOuterPanel("option", "duration.open", 340);

easing

Type: String | Array | Object Default: "swing"

Defines the animation easing for the open(), close(), slide(), hide(), peep(), deactivate() and resize() methods, assuming animation is enabled. A String or Array value applies to all methods. To set the option for each method independently pass an Object mapping method names to String or Array values. Methods omitted from the Object or methods without String or Array values will use the default value.

All easings supported by Velocity.js are supported except for one-item arrays (step easing).

// Set the easing to "ease-in" for all methods.
$("#element").proOuterPanel({
    easing: "ease-in"
});
// Set the easing for each method independently.
$("#element").proOuterPanel({
    easing: {
        open: "easeOutSine",
        close: "easeInCubic",
        peep: "easeInQuart",
        slide: "easeInOutQuart",
        deactivate: "easeInQuad",
        hide: [0.17, 0.67, 0.83, 0.67],
        resize: [250, 15]
    }
});
// Updates the open state only, assuming an object was set on initialisation
$("#element").proOuterPanel("option", "duration.easing", "swing");

handleSize

Type: Number Default: "auto"

Defines the height of the panel handle for north and south panels or the width of the panel handle for east and west panels. The string value "auto" will use the natural width or height of the handle element defined by the theme CSS. Numerical values refer to px units.

$("#element").proOuterPanel({
    handleSize: 20
});

maxSize

Type: Number | String Default: null

Defines the maximum height of north and south panels or the maximum width of east and west panels. The string value "auto" will allow the panel to use all available space within the layout. Numerical values refer to px units. If null the panel cannot be resized larger than its current size except using the size option.

// Use all available space.
$("#element").proOuterPanel({
    maxSize: "auto"
});
// Set the maximum size to 400px.
$("#element").proOuterPanel({
    maxSize: 400
});

minSize

Type: Number | String Default: null

Defines the minimum height of north and south panels or the minimum width of east and west panels. Numerical values refer to px units. If null the panel cannot be resized smaller than its current size except using the size option.

An in-built absolute minimum panel size of 10px is enforced at all times for a better user experience. Consider the scenario where a user is able to resize a panel to 0. The panel would appear to be closed even when open and toggling the panel between open and closed would have no visible effect.

// Use all available space.
$("#element").proOuterPanel({
    minSize: "auto"
});
// Set the maximum size to 400px.
$("#element").proOuterPanel({
    minSize: 400
});

modal

modal: Boolean Default: false

Defines whether the panel is modal when sliding. ProPanelLayout manages modal panels by automatically closing all other sliding panels and enabling an overlay element. If animation is enabled the overlay element fades in and out using the same duration as the modal sliding panel.

$("#element").proOuterPanel({
    modal: true
});

peepSize

Type: Number Default: 0

Defines the visible size of the panel when peeping. The peeping state is visibly between the open and closed states and provides even more scope for innovative layouts, especially when combined with a nested layout. The value is automatically capped at the current panel size.

// Leave 50px of panel visible when peeping
$("#element").proOuterPanel({
    peepSize: 50
});

persist

Type: String Default: 'size,state'

Defines which options to persist. An empty string disables persistence. ProOuterPanel uses LocalStorage to persist widget options across page loads and automatically handles putting and getting stored options. The string must be a comma separated list of options. Any option can be persisted, but normally you should only need to persist options that can be changed through the user interface.

// Persist panel state only
$("#element").proOuterPanel({
    persist: "state"
});

responsiveSize

Type: Boolean Default: true

Defines whether ProPanelLayout can override the panel size in response to the available layout space. For responsiveSize to have any effect the panel minSize option must be defined. When responsiveSize: true ProPanelLayout will automatically reduce the panel size towards the minSize when needed and increase the panel size towards the original size when possible.

$("#element").proOuterPanel({
    responsiveSize: false
});

responsiveState

Type: Boolean Default: true

Defines whether ProPanelLayout can override the panel state in response to the available layout space. When responsiveState: true ProPanelLayout will automatically set the panel state to free up space. This means open panels will be forced into their closedState when needed and will resume their original state when possible.

$("#element").proOuterPanel({
    responsiveState: false
});

showHandle

Type: Boolean | String | Object Default: true

Defines whether the panel handle is displayed in the open, closed, sliding, hidden, peeping and inactive states. A true or false value applies to all states. To set the option for each state independently pass either a string of states for which to showHandle, or an Object mapping states to true or false values. States omitted from the Object or states without Boolean values will use the default value.

// Hides the panel handle for all states
$("#element").proOuterPanel({
    showHandle: false
});
// Shows the panel handle for open and closed states only
$("#element").proOuterPanel({
    showHandle: "open,closed"
});
// Shows the panel handle when open and sliding and hides the panel handle in other states
$("#element").proOuterPanel({
    showHandle: {
        open: true,
        sliding: true,
        peeping: false,
        closed: false,
        hidden: false,
        inactive: false
    }
});
// Updates the open state only, assuming an object was set on initialisation
$("#element").proOuterPanel("option", "showHandle.open", false);

showToggle

Type: Boolean | String | Object Default: true

Defines whether the toggle button is displayed in the panel handle in the open, closed, sliding, hidden, peeping and inactive states. A true or false value applies to all states. To set the option for each state independently pass either a string of states for which to showToggle, or an Object mapping states to true or false values. States omitted from the Object or states without Boolean values will use the default value.

// Hides the toggle button for all states
$("#element").proOuterPanel({
    showToggle: false
});
// Shows the toggle button for open and closed states only
$("#element").proOuterPanel({
    showToggle: "open,closed"
});
// Shows the toggle button when open and sliding and hides the toggle button in other states
$("#element").proOuterPanel({
    showToggle: {
        open: true,
        sliding: true,
        peeping: false,
        closed: false,
        hidden: false,
        inactive: false
    }
});
// Updates the open state only, assuming an object was set on initialisation
$("#element").proOuterPanel("option", "showToggle.open", false);

size

Type: Number | String Default: "auto"

Defines the height of north and south panels or the width of east and west panels. The value "auto" will use the panel's natural width or height. Numerical values refer to px units.

Care should be taken when using a value of "auto". It works best when the panel content has well defined dimensions e.g. an image with explicit dimensions or an element with CSS width and height properties. If the panel content is floated, positioned, not yet loaded or rendered, or liable to expand horizontally, the size will be unpredicable and could result in unintended (but correct) behaviour on initialisation.

// Automatically calculate the panel size.
$("#element").proOuterPanel({
    size: "auto"
});
// Set the size to 400px.
$("#element").proOuterPanel({
    size: 400
});

state

Type: String Default: null

Defines the state of the panel.

  • "open" – the panel is fully visible.
  • "closed" – the panel is fully hidden, but the panel handle remains visible.
  • "sliding" – the panel is fully visible, but the center panel is not resized.
  • "hiding" – the panel is fully hidden, including the panel handle.
  • "peeping" – the panel is partly visible.
  • "inactive" – the panel is fully hidden and is not the active panel of the layout.
$("#element").proOuterPanel({
    state: "hidden"
});

theme

Type: String Default: "silvercore"

Defines the theme class applied to the panel, handle and toggle elements. The theme class is the string "pro-outer-panel--theme-value". For this option to have any effect, related CSS styles that make use of the theme class must be present..

$("#element").proOuterPanel({
    theme: "my-theme" // Creates a class of "pro-outer-panel--theme-my-theme"
});

toggleAction

Type: Object Default: null

Defines the method called for each panel state when the toggle() method is called or the toggle button is clicked. The value is an object map of states to methods.

// When the panel is open or sliding and toggled the close() method is called.
// When the panel is peeping, closed, hidden or inactive and toggled the open() method is called.
$("#element").proOuterPanel({
    toggleAction: {
        open: "close",
        sliding: "close",
        peeping: "open",
        closed: "open",
        hidden: "open",
        inactive: "open"
    },
});

type

Type: String Default: "west"

Defines the panel type.

  • "north" – the panel is positioned at the top of the layout.
  • "south" – the panel is positioned at the bottom of the layout.
  • "east" – the panel is positioned at the right of the layout.
  • "west" – the panel is positioned at the left of the layout.
$("#element").proOuterPanel({
    type: "east"
});

Methods

Widget methods are invoked by passing the method name to the jQuery plugin:

$("#element").proOuterPanel("enable");

If a method accepts arguments they can be passed after the method name:

$("#element").proOuterPanel("option", "disabled", false);

Most methods return the jQuery object for chaining:

$("#element").proOuterPanel("enable").show();

However, some methods might return a value:

var disabled = $("#element").proOuterPanel("option", "disabled"); // false

addLayout(layoutOptions[, widgetName[, element]])

Adds a layout to the panel. You should always use the addLayout() method or layout option to create nested layouts so that ProOuterPanel can efficiently handle the layout life cycle and optimise rendering performance.

Arguments

layoutOptions
Type: Object
Layout options corresponding to the type of layout being created.
widgetName
Type: String
The name of a compatible layout widget plugin. Currently the only supported layout widget is ProPanelLayout. If omitted the default value "proPanelLayout" is used.
element
Type: Selector | jQuery | Element
The element to initialise. If the value returns multiple elements only the first element is used. If omitted or an element cannot be selected the panel element will become the layout widget.

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("addLayout", {
    center: {
        element: "#center",
        minWidth: 200,
        minHeight: 400
    },
    north: {
        element: "#north"
    },
    south: {
        element: "#south"
    },
    east: {
        element: "#east"
    },
    west: {
        element:" #west"
    }
});

autoClose([duration[, easing[, callback]]])

Calls either the close(),peep() or hide() method depending on the value of the closedState option. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to execute when the action completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("autoClose")

clearStoredOptions()

Clears all the LocalStorage data for the widget.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("clearStoredOptions");

close([duration[, easing[, callback]]])

Closes the panel. The panel state is set to "closed" and putStoredOptions() is called. If animation is enabled the panel will closing using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Close the panel using default duration and easing.
$("#element").proOuterPanel("close");
// Close the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("close", "fast", "swing", function () {
    // do something
});

deactivate([duration[, easing[, callback]]])

Deactivates the panel. The panel state is set to "inactive" and putStoredOptions() is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Deactivate the panel using default duration and easing.
$("#element").proOuterPanel("deactivate");
// Deactivate the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("deactivate", "fast", "swing", function () {
    // do something
});

destroy()

Destroys the widget along with all associated data, elements and bindings. Restores the widget element to its pre-widget state. Any layout associated with the panel will also be destroyed.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("destroy")

disable()

Disables the widget UI completely by setting disabled: true. All user interaction with the panel, handle and toggle is ignored.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("disable")

enable()

Enables the widget UI completely by setting disabled: false. All user interaction with the panel is handled according to the options set.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("enable")

getStoredOptions()

Gets the stored options for this widget from LocalStorage. The option values retrieved are defined by the persist option.

Arguments

This method does not accept any arguments

Return

Type: Object
The stored options.

$("#element").proOuterPanel("getStoredOptions");
// Object {size: 430, state: "open"}

hide([duration[, easing[, callback]]])

Hides the panel. The panel state is set to "hidden" and putStoredOptions() is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Hide the panel using default duration and easing.
$("#element").proOuterPanel("hide");
// Hide the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("hide", "fast", "swing", function () {
    // do something
});

localStorageKey()

Gets the key used to store options in LocalStorage. The value uses the format "silvercore_proOuterPanel_widgetId".

Arguments

This method does not accept any arguments

Return

Type: String
The LocalStorage key.

$("#element").proOuterPanel("localStorageKey"); // "silvercore_proOuterPanel_element"

maximize([duration[, easing[, callback]]])

Maximizes the panel size. The panel size is set to maxSize (constrained by the available space) and putStoredOptions() is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Maximize the panel using default duration and easing.
$("#element").proOuterPanel("maximize");
// Maximize the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("maximize", "fast", "swing", function () {
    // do something
});

minimize([duration[, easing[, callback]]])

Minimizes the panel size. The panel size is set to minSize is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Minimize the panel using default duration and easing.
$("#element").proOuterPanel("minimize");
// Minimize the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("minimize", "fast", "swing", function () {
    // do something
});

open([duration[, easing[, callback]]])

Opens the panel. The panel state is set to "open" and putStoredOptions() is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Open the panel using default duration and easing.
$("#element").proOuterPanel("open");
// Open the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("open", "fast", "swing", function () {
    // do something
});

option()

Gets the values of all options.

Arguments

This method does not accept any arguments

Return

Type: Object
An object containing all option values.

$("#element").proOuterPanel("option")

option(optionName)

Gets the value of a single option.

Arguments

optionName
Type: String
The option to get. If an option is set with an object you can get an individual property of the object using dot notation e.g. "optionName.key"

Return

Type: Any
The option value. The type depends on the option.

$("#element").proOuterPanel("option", "enabled")

option(options)

Sets multiple options.

Arguments

options
Type: Object
A map of option-value pairs.

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("option", {
    disabled: true
})

option(optionName, value)

Sets a single option.

Arguments

optionName
Type: String
The option to set. If an option is set with an object you can set an individual property of the object using dot notation e.g. "optionName.key"
value
Type: Any
The value to set. The type depends on the option.

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("option", "disabled", true)

peep([duration[, easing[, callback]]])

Peeps the panel. The panel state is set to "peeping" and putStoredOptions() is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Peep the panel using default duration and easing.
$("#element").proOuterPanel("peep");
// Peep the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("peep", "fast", "swing", function () {
    // do something
});

putStoredOptions()

Puts the stored options for this widget to LocalStorage. The option values stored are defined by the persist option.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proOuterPanel("putStoredOptions");

resize([size[, duration[, easing[, callback]]]])

Resizes the panel. The panel size is set to the defined size (constrained by the available space, minSize and maxSize) and putStoredOptions() is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

size
Type: Number | String
Defines the height of north and south panels or the width of east and west panels. The value "auto" will use the panel's natural width or height. Numerical values refer to px units. If a value is omitted the panel's initial size is used.
duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Maximize the panel using default duration and easing.
$("#element").proOuterPanel("resize");
// Maximize the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("resize", "fast", "swing", function () {
    // do something
});

slide([duration[, easing[, callback]]])

Slides the panel. The panel state is set to "sliding" and putStoredOptions() is called. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Slide the panel using default duration and easing.
$("#element").proOuterPanel("slide");
// Slide the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("slide", "fast", "swing", function () {
    // do something
});

toggle(duration[, easing[, callback]]]])

Calls either the open(), close(), slide(), peep(), hide() or deactivate() method depending on the value of the toggleAction option. If animation is enabled the panel will animate using the values set by the duration, easing and animateCenter options.

Arguments

duration
Type: Number | String
Overrides the duration option. Duration can be defined in milliseconds or by using jQuery's named durations "slow" (600ms), "normal" (400ms) and "fast" (200ms). A duration of 0 effectively disables animation.
easing
Type: String | Array
Overrides the easing option. All easings supported by Velocity.js are supported except for one-item arrays (step easing).
callback
Type: Function
A function to call when the method completes, after any animation.

Return

Type: jQuery
The widget element for chaining.

// Toggle the panel using default duration and easing.
$("#element").proOuterPanel("toggle");
// Toggle the panel using the specified duration and easing, calling the callback when animation completes.
$("#element").proOuterPanel("toggle", "fast", "swing", function () {
    // do something
});

Events

Events can be handled by binding a function to the widget element using an event handler or by passing a function to the callback option on or after initialisation. Both methods can be used together on the same widget. When an event is triggered the bound event handlers are invoked before any callbacks are executed. Either method can be used to cancel a cancellable event, either by calling e.preventDefault() or returning false. If a handler and a callback are bound to the same event and the handler cancels the event the callback is still executed.

JQuery UI Widget Factory, on which ProOuterPanel is built, provides inbuilt functionality to trigger widget events and when used this way generates event names automatically. However, these generated event names are different for different verions of jQuery UI and are slated to change again in the future:

widgetEventPrefix: The prefix prepended to the name of events fired from this widget. For example the widgetEventPrefix of the draggable widget is "drag", therefore when a draggable is created, the name of the event fired is "dragcreate". By default the widgetEventPrefix of a widget is its name. Note: This property is deprecated and will be removed in a later release. Event names will be changed to widgetName:eventName (e.g. "draggable:create").Widget Factory | jQuery UI API Documentation

In order to create a more stable widget, regardless of the version of jQuery UI Widget Factory running, ProOuterPanel always triggers events with names using the format widgetname:eventname (lowercase). Therefore, you should always use the event names as documented, not the event name you might expect to use based on the version of jQuery UI running.

afterClose(event, eventData)

Type: "proouterpanel:afterclose" Cancellable: no

Triggered after the panel closes.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    afterClose: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "afterClose", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:afterclose", function (event, eventData) {
    // do something
});

afterDeactivate(event, eventData)

Type: "proouterpanel:afterdeactivate" Cancellable: no

Triggered after the panel deactivates.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    afterDeactivate: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "afterDeactivate", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:afterdeactivate", function (event, eventData) {
    // do something
});

afterHide(event, eventData)

Type: "proouterpanel:afterhide" Cancellable: no

Triggered after the panel hides.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    afterHide: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "afterHide", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:afterhide", function (event, eventData) {
    // do something
});

afterOpen(event, eventData)

Type: "proouterpanel:afteropen" Cancellable: no

Triggered after the panel opens.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    afterOpen: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "afterOpen", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:afteropen", function (event, eventData) {
    // do something
});

afterPeep(event, eventData)

Type: "proouterpanel:afterpeep" Cancellable: no

Triggered after the panel peeps.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    afterPeep: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "afterPeep", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:afterpeep", function (event, eventData) {
    // do something
});

afterResize(event, eventData)

Type: "proouterpanel:afterresize" Cancellable: no

Triggered after the panel resizes by both the resize() method and drag resizing.

Arguments

event
Type: Event
A jQuery Event object.
eventData.size
Type: Number
The CSS size of the panel. Depending on the panel type this refers to the width or height CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    afterResize: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "afterResize", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:afterresize", function (event, eventData) {
    // do something
});

afterSlide(event, eventData)

Type: "proouterpanel:afterslide" Cancellable: no

Triggered after the panel slides.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    afterSlide: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "afterSlide", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:afterslide", function (event, eventData) {
    // do something
});

beforeClose(event, eventData)

Type: "proouterpanel:beforeclose" Cancellable: yes

Triggered before the panel closes.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    beforeClose: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "beforeClose", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:beforeclose", function (event, eventData) {
    // do something
});

beforeDeactivate(event, eventData)

Type: "proouterpanel:beforedeactivate" Cancellable: yes

Triggered before the panel deactivates.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    beforeDeactivate: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "beforeDeactivate", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:beforedeactivate", function (event, eventData) {
    // do something
});

beforeHide(event, eventData)

Type: "proouterpanel:beforehide" Cancellable: yes

Triggered before the panel hides.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    beforeHide: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "beforeHide", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:beforehide", function (event, eventData) {
    // do something
});

beforeOpen(event, eventData)

Type: "proouterpanel:beforeopen" Cancellable: yes

Triggered before the panel opens.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    beforeOpen: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "beforeOpen", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:beforeopen", function (event, eventData) {
    // do something
});

beforePeep(event, eventData)

Type: "proouterpanel:beforepeep" Cancellable: yes

Triggered before the panel peeps.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    beforePeep: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "beforePeep", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:beforepeep", function (event, eventData) {
    // do something
});

beforeResize(event, eventData)

Type: "proouterpanel:beforeresize" Cancellable: yes

Triggered before the panel resizes by both the resize() method and drag resizing.

Arguments

event
Type: Event
A jQuery Event object.
eventData.size
Type: Number
The CSS size of the panel. Depending on the panel type this refers to the width or height CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    beforeResize: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "beforeResize", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:beforeresize", function (event, eventData) {
    // do something
});

beforeSlide(event, eventData)

Type: "proouterpanel:beforeslide" Cancellable: yes

Triggered before the panel slides.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    beforeSlide: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "beforeSlide", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:beforeslide", function (event, eventData) {
    // do something
});

duringClose(event, eventData)

Type: "proouterpanel:duringclose" Cancellable: no

Triggered during panel closing, only if animation is enabled.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
eventData.elements
Type: Array<Element>
An array containing the animated elements. This value is passed on directly from the Velocity.js progress callback.
eventData.complete
Type: Number
The call's completion percentage (as a decimal value). This value is passed on directly from the Velocity.js progress callback.
eventData.remaining
Type: Number
How much time remains until the call completes (in ms). This value is passed on directly from the Velocity.js progress callback.
eventData.start
Type: Number
The absolute time at which the call began (in Unix time). This value is passed on directly from the Velocity.js progress callback.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    duringClose: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "duringClose", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:duringclose", function (event, eventData) {
    // do something
});

duringDeactivate(event, eventData)

Type: "proouterpanel:duringdeactivate" Cancellable: no

Triggered during panel deactivation, only if animation is enabled.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
eventData.elements
Type: Array<Element>
An array containing the animated elements. This value is passed on directly from the Velocity.js progress callback.
eventData.complete
Type: Number
The call's completion percentage (as a decimal value). This value is passed on directly from the Velocity.js progress callback.
eventData.remaining
Type: Number
How much time remains until the call completes (in ms). This value is passed on directly from the Velocity.js progress callback.
eventData.start
Type: Number
The absolute time at which the call began (in Unix time). This value is passed on directly from the Velocity.js progress callback.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    duringDeactivate: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "duringDeactivate", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:duringdeactivate", function (event, eventData) {
    // do something
});

duringHide(event, eventData)

Type: "proouterpanel:duringhide" Cancellable: no

Triggered during panel hiding, only if animation is enabled.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
eventData.elements
Type: Array<Element>
An array containing the animated elements. This value is passed on directly from the Velocity.js progress callback.
eventData.complete
Type: Number
The call's completion percentage (as a decimal value). This value is passed on directly from the Velocity.js progress callback.
eventData.remaining
Type: Number
How much time remains until the call completes (in ms). This value is passed on directly from the Velocity.js progress callback.
eventData.start
Type: Number
The absolute time at which the call began (in Unix time). This value is passed on directly from the Velocity.js progress callback.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    duringHide: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "duringHide", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:duringhide", function (event, eventData) {
    // do something
});

duringOpen(event, eventData)

Type: "proouterpanel:duringopen" Cancellable: no

Triggered during panel opening, only if animation is enabled.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
eventData.elements
Type: Array<Element>
An array containing the animated elements. This value is passed on directly from the Velocity.js progress callback.
eventData.complete
Type: Number
The call's completion percentage (as a decimal value). This value is passed on directly from the Velocity.js progress callback.
eventData.remaining
Type: Number
How much time remains until the call completes (in ms). This value is passed on directly from the Velocity.js progress callback.
eventData.start
Type: Number
The absolute time at which the call began (in Unix time). This value is passed on directly from the Velocity.js progress callback.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    duringOpen: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "duringOpen", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:duringopen", function (event, eventData) {
    // do something
});

duringPeep(event, eventData)

Type: "proouterpanel:duringpeep" Cancellable: no

Triggered during panel peeping, only if animation is enabled.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
eventData.elements
Type: Array<Element>
An array containing the animated elements. This value is passed on directly from the Velocity.js progress callback.
eventData.complete
Type: Number
The call's completion percentage (as a decimal value). This value is passed on directly from the Velocity.js progress callback.
eventData.remaining
Type: Number
How much time remains until the call completes (in ms). This value is passed on directly from the Velocity.js progress callback.
eventData.start
Type: Number
The absolute time at which the call began (in Unix time). This value is passed on directly from the Velocity.js progress callback.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    duringPeep: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "duringPeep", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:duringpeep", function (event, eventData) {
    // do something
});

duringResize(event, eventData)

Type: "proouterpanel:duringresize" Cancellable: no

Triggered during panel resizing by both the resize() method, if animation is enabled, and drag resizing.

Arguments

event
Type: Event
A jQuery Event object.
eventData.size
Type: Number
The CSS size of the panel. Depending on the panel type this refers to the width or height CSS property.
eventData.elements
Type: Array<Element>
An array containing the animated elements. This value is passed on directly from the Velocity.js progress callback.
eventData.complete
Type: Number
The call's completion percentage (as a decimal value). This value is passed on directly from the Velocity.js progress callback.
eventData.remaining
Type: Number
How much time remains until the call completes (in ms). This value is passed on directly from the Velocity.js progress callback.
eventData.start
Type: Number
The absolute time at which the call began (in Unix time). This value is passed on directly from the Velocity.js progress callback.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    duringResize: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "duringResize", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:duringresize", function (event, eventData) {
    // do something
});

duringSlide(event, eventData)

Type: "proouterpanel:duringslide" Cancellable: no

Triggered during panel sliding, only if animation is enabled.

Arguments

event
Type: Event
A jQuery Event object.
eventData.position
Type: Number
The CSS position of the panel. Depending on the panel type this refers to the top, right, bottom or left CSS property.
eventData.elements
Type: Array<Element>
An array containing the animated elements. This value is passed on directly from the Velocity.js progress callback.
eventData.complete
Type: Number
The call's completion percentage (as a decimal value). This value is passed on directly from the Velocity.js progress callback.
eventData.remaining
Type: Number
How much time remains until the call completes (in ms). This value is passed on directly from the Velocity.js progress callback.
eventData.start
Type: Number
The absolute time at which the call began (in Unix time). This value is passed on directly from the Velocity.js progress callback.
// Setting a callback on initialisation
$("#element").proOuterPanel({
    duringSlide: function (event, eventData) {
        // do something
    }
});
// Setting a callback after initialisation
$("#element").proOuterPanel("option", "duringSlide", function (event, eventData) {
    // do something
});
// Binding a handler to the event
$("#element").on("proouterpanel:duringslide", function (event, eventData) {
    // do something
});