Kwicks for jQuery (v2.2.1)

Welcome to the Kwicks for jQuery home page. Kwicks is a plugin providing sexy sliding panels with an emphasis on navigational interaction. Kwicks was originally a port of a MooTools effect (of the same name), but has since evolved into a highly configurable and versatile UI component. Please check out the examples to see it in action.

New in v2.2.1

This is a patch release with no API changes, and is aimed at fixing a rare and sporadic bug that causes styles to not initialize properly.

New in v2.2.0

Kwicks v2.2.0 is a substantial update that addresses several feature requests (keep them coming)! Here are the main updates since the last release:

  • New events and a refactor of the existing events.
    Important: the new events are awesome, but not compatible with earlier versions - be sure to read the new docs before updating!
  • There is now a kwicks-collapsed class to go along with the pre-existing kwicks-expanded class (credit: gguerrero).
  • There is now a built-in slideshow behavior (credit: gguerrero).
  • Panel spacing can now be specified as a percentage (credit: Duke3D).
  • There is now a $().kwicks('destroy') method.
  • The $().kwicks('expand') method now accepts a delay option).
  • The menu behavior has new options: delayMouseIn, delayMouseOut, selectOnClick, and deselectOnClick.

Getting Started

Dependencies

Source

Kwicks is available on GitHub. You can download Kwicks 2.2.1 (with examples) here [zip], or browse the source here.

Markup

Kwicks has pretty relaxed markup requirements:

  1. A container element with two classes: kwicks and kwicks-horizontal|vertical (depending on the orientation of this instance).

  2. A single level of nested "panel" elements.

Unordered lists are a good semantic fit for most Kwicks use cases:

<ul class='kwicks kwicks-horizontal'>
    <li></li>
    <li></li>
    <li></li>
    <li></li>
</ul>

However, as noted above, Kwicks doesn't require that unordered lists be used. For example, see the Anchor Markup example.

If you want one of the panels to be selected on initialization, simply add a kwicks-selected class to it.

The Code

Kwicks follows the usual jQuery plugin conventions:

// instantiate kwicks
$(element).kwicks(opts);

// invoke a method
$(element).kwicks('method-name' [, param]);

// handle events
$(element).on('event-name.kwicks', handler);

Options

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 as minSize 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

Methods

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 a kwicks-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');

Class Names

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.

Events

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();
});

Browser Support

Kwicks is supported in the following browsers:

  • Chrome 12+
  • FF 3.6+
  • IE7+
  • Opera 11+
  • Safari 5+

Special Considerations

Important styling information: Please note that in order to provide the smoothest possible animations, the following style changes are made by the script:

  • The Kwicks container is converted to relative positioning.
  • All panels are converted to absolute positioning.
  • To keep things as "jitter free" as possible, panel styles are set by overriding the whole style attribute, which currently causes any previously specified inline styles to be lost. Make sure any styles you want to keep are set externally with a selector, rather than inline.
  • Margins on the panels are stripped, but the spacing option is respected through the absolute positioning.
  • Even though the panels' margins are stripped, in order for them to look correct in non-JS enabled browsers, they should still be given margins that correspond to the spacing option (if any). I strongly recommend that you look at the CSS in the examples.

Bugs, feature requests, etc:

Anything pertaining to bugs and/or the development of Kwicks can be dicussed on the GitHub issue queue.

Previous Versions

Downloads, documentation, and examples for previous versions: