Kwicks for jQuery

The following options may be specified when instantiating a new Kwicks instance:

maxSize|minSize:(Type: number|string)

The width or height of a fully expanded|collapsed panel. If the value is a number, then the unit will be px. If the value is a string, then the units must be specified (px or %).

Examples: 400, '250px', '20%'

Please note that % dimensions are calculated based on the remainder after spacing has been removed (see the spacing option).

If isVertical is true, then minSize and maxSize refer to the height of the panel, otherwise they refer to the width.

Note that you may specify maxSize OR minSize, but not both.

Default: realistically, you're going to want to set this, but if you don't Kwicks will attempt to identify some reasonable behavior.

spacing:(Type: number|string)

The distance separating each panel. This option follows the same pattern asminSize and maxSize: if the value is a number, then the unit will be px. If the value is a string, then the units must be specified (px or %).

If the specified unit is %, then the spacing is a percentage of the container's size.

Examples: 5, '4px', '2%'

Default: 5

duration:(Type: number)

The number of milliseconds for the animation to run.

Default: 500

isVertical:(Type: bool)

Indicates whether or not the panels should be arranged vertically.

Default: false

easing:(Type: string)

The name of the easing function to use for the animation.

Default: none

autoResize:(Type: bool)

Indicates whether or not Kwicks should automatically resize itself based on window resizes.

If this is disabled (or a container resize occurs due to something other than a window resize), you may use the $(container).kwicks('resize') method to trigger the resize logic manually.

Default: true

behavior:(Type: string)

Indicates if/what out-of-the-box behavior should be enabled. These are provided purely as a convenience for common interactions, so if one of these doesn't satisfy your needs, please continue reading below on how to control Kwicks programmatically.

Default: none

Possible values:

 

• 'menu'

  By default, the menu behavior expands panels on mouseenter, selects panels on click, and reverts all panels to a default state when the mouse leaves the container.

  This behavior exposes some additional menu-only options to customize these interactions:

  delayMouseIn:(Type: number)

  The number of milliseconds to wait before expanding a panel on mouseenter.

  Default:0

  delayMouseOut:(Type: number)

  The number of milliseconds to wait before reverting panels to a default state when the mouse leaves the container.

  Default:0

  selectOnClick:(Type: bool)

  Indicates whether or not panels should be selected on click.

  Default:true

  deselectOnClick:(Type: bool)

  Indicates whether or not currently selected panels should be deselected on click.

  Default:false

• 'slideshow'

  By default, the slideshow behavior configures successively panels to automatically expand at a regular interval. Additionally, mouseenter causes the progression to "pause" and the hovered panel to expand. Once the mouse leaves, the slideshow behavior resumes.

  This behavior exposes some additional slideshow-only options to customize these interactions:

  interval:(Type: number)

  The number of milliseconds to wait before expanding the next panel.

  Default:2500

  interactive:(Type: bool)

  Indicates whether or not the mouse interactions described above should be enabled.

  Default:true

Kwicks provides several API methods that may be used for programmatic control and inspection of the plugin.

expand

Expands the panel with the specified index (use -1 to expand none).

$(container).kwicks('expand', index);

Alternatively, the expand method may also be invoked directly on a panel (rather than the container). For example,

$(container).children().eq(2).kwicks('expand');

...performs the same action as...

$(container).kwicks('expand', 2);

Sometimes it's useful to provide a slight delay before expanding a panel. To support this, the expand method may be given a delay option (specified in milliseconds):

$(container).kwicks('expand', 3, { delay: 500 });

expanded

Returns the index of the currently expanded panel (or -1 if no panels are expanded).

var index = $(container).kwicks('expanded');

select

Selects the panel with the specified index (use -1 to select none). Please note that most use cases will not require the use of select. Calling select has the same effect as calling expand, except that select is stateful. That is, once a panel has been selected, it will maintain that state even after other panels have been expanded. When $(element).kwicks('expand', -1); is invoked, the currently selected panel will be expanded, if it exists.

$(container).kwicks('select', index);

Just like expand, select may also be invoked directly on a panel:

$(panel).kwicks('select');

Note: if you want a panel to be automatically selected on initialization, simply add akwicks-selected class to its markup.

selected

Returns the index of the currently selected panel (or -1 if no panels are selected).

var index = $(container).kwicks('selected');

resize

Forces panel dimensions to be recalculated in response to a potential change in the container dimensions. This can be useful if the autoResize option has been disabled, or if a container resize occurs due to something other than a window resize.

$(container).kwicks('resize');

destroy

Removes the kwicks functionality completely. All classes, style attributes, and event handlers added by the kwicks plugin are reverted.

$(container).kwicks('destroy');

Kwicks adds several different classes to the DOM elements that may be useful for styling purposes.

kwicks

If not already present, Kwicks will add this class to the container element.

kwicks-horizontal|kwicks-vertical

If not already present, Kwicks will add the appropriate orientation class to the container element.

kwicks-processed

This is intended purely for internal use, and is added to the container element once the plugin has been initialized.

kwicks-expanded

The currently expanded panel (if there is one) will be given this class.

kwicks-collapsed

Whenever a panel is expanded, all other panels are given this class.

kwicks-selected

The currently selected panel (if there is one) will be given this class.

Note that if you'd like a panel to be selected on initialization, you may add this class to your markup.

Certain Kwicks interactions trigger events that can be used to react to (or cancel) behavior.

expand.kwicks

Fired before a panel is expanded.

$(container).on('expand.kwicks', function(e, data) {
    // panel index (or -1 if we're expanding none)
    console.log(data.index);

    // panel reference (or null if we're expanding none)
    console.log(data.expanded);

    // an array of all collapsed panels
    // (will be empty if we're expanding none)
    console.log(data.collapsed);

    // index of previously expanded panel (-1 if there wasn't one)
    console.log(data.oldIndex);

    // reference to previously expanded panel
    // (or null if there wasn't one)
    console.log(data.oldExpanded);

    // boolean indicating whether or not a previous animation 
    // is still running
    console.log(data.isAnimated);

    // prevent the panel from expanding
    e.preventDefault();
});

expand-complete.kwicks

Fired after a panel has been fully expanded (but not if another expand has been triggered prior to the animation completing).

$(container).on('expand-complete.kwicks', function(e, data) {
    // data contains same properties as the `expand.kwicks` event
});

select.kwicks

Fired before a panel is selected.

$(container).on('select.kwicks', function(e, data) {
    // panel index (or -1 if we're selecting none)
    console.log(data.index);

    // panel reference (or null if we're selecting none)
    console.log(data.selected);

    // an array of all unselected panels
    // (will be all panels if we're selecting none)
    console.log(data.unselected);

    // index of previously selected panel (-1 if there wasn't one)
    console.log(data.oldIndex);

    // reference to previously selected panel
    // (or null if there wasn't one)
    console.log(data.oldSelected);

    // prevent the panel from being selected
    e.preventDefault();
});