Take the demo closest to what you need, read the instructions in the CSS and code, add content, and pretty up the styles. Go ahead, I'll wait. What, you're not done yet and want some more information? Here's a quick tour. Markup for a vertical splitter looks like this:
<div id="MySplitter"> <div id="LeftPane"> Left content goes here </div> <div id="RightPane"> Right content goes here </div> </div>
The top-level div encloses two child divs that serve as the left and right panes. The plugin doesn't care about the id names, but they simplify applying styles in a stylesheet. The splitter documentation below refers to the first pane as pane A, since it is either the left pane of a vertical splitter or the top pane of a horizontal splitter. Similarly, the second pane is pane B, the right or bottom pane. The plugin dynamically adds the splitbar that goes between the panes. When the documentation refers to the size of a pane, it means the variable dimension--width for a vertical splitter and height for a horizontal one.
Any splitter will also have stylesheet rules to provide visual styles and dimensions. It should have distinctive styling for the splitbar with visual clues that the bar can be moved by the user. The demo pages use color changes and several small bitmaps for the splitbars to make them stand out.
To create the splitter, put a line of code in a .ready() handler to select the MySplitter div in a jQuery object and pass it to the splitter plugin:
$().ready(function(){
$("#MySplitter").splitter({type: 'v'});
});
Congratulations, there's a vertical splitter in your document!
Users can move the splitbar in three ways:
$().splitter({accessKey: "I"}). Press that key (e.g, Alt-Shift-I on a PC, Cmd-Shift-I on a Mac) to select the splitbar, then use the arrow keys to move it.Splitter options described below can modify most aspects of this behavior, such as the type of cursor used on the splitter, the tab order of the splitbar and whether the splitbar is in the page's tab order at all. By setting size limits on the two panes, you can prevent the splitter from making one of the panes too big or small.
It is also possible to move the splitbar position programmatically. Trigger the splitter's resize event, passing it an array with a single number that indicates the new splitbar position, in pixels from the top/left edge:
$("#MySplitter").trigger("resize", [ 200 ]);
Movement of the splitbar through this type of resize is still subject to any size and position constraints that were set by options or stylesheet rules.
By default, the splitbar is set to the center of the splitter area at initialization, giving equal area to both panes. To set a different starting splitbar position, use the initA (left/top pane) or initB (bottom/right pane) options to the plugin. Only one of the values should be set. If you specify the value true, the plugin will obtain the size from the width/height property set though the stylesheet. Alternatively, you can use initA or initB to specify the size of the pane (in pixels).
Setting initA or initB when calling the plugin also tells it which pane should be resized when the splitter container is resized. By default, pane A maintains its size and B will grow or shrink unless the minB or maxB constraints force A to change. By specifying initB in the plugin options, pane B maintains its size and pane A is resized.
The splitter plugin supports resizing the splitter container that holds both panes, but it must be notified of a change via a resize event. Internet Explorer does this automatically, but other browsers do not. In the example above, #MySplitter is defined to be a 400x300 pixel fixed width. To resize it to 400x400 pixels, you could use this code:
$("#MySplitter").css("height", "400px").trigger("resize");
If the splitter container has a fluid width, it extends the full width of its containing element. That means it will automatically resize whenever the parent element's size changes. However, the splitter needs to be notified when this occurs so that it can adjust the panes as well. The most common need for a resize is when the user changes the size of the browser's window; it just takes a few extra lines in the .ready() handler to pass along the window's resize event to the splitter whenever the browser window is resized:
$(document).ready(function(){
$("#MySplitter").splitter({direction: 'v'});
$(window).bind("resize", function(){
$("#MySplitter").trigger("resize");
});
});
You can create a semi-fluid splitter container by setting a minimum and maximum size for the container. This change to the style for #MySplitter would allow its width to vary between 300 and 600 pixels, based on the size of the parent container:
#MySplitter { min-width: 300px; max-width: 600px; height: 300px; }
The 3-pane splitter demo demonstrates resizing the splitter container to fit the height and width of the browser window. The splitter plugin automatically sends a resize event to each pane whenever the splitbar is moved or the outer container is resized, so no extra work is needed to support nested splitter containers.
For performance reasons, the splitter plugin caches the size of the padding and borders for the splitter container and both panes when the splitter is created. Do not change these values after creating the splitter.
When no size constraint options are specified for either pane, the plugin allows the splitbar to be moved so it totally obscures the content of one of the panes. A scroll bar or padding may still be visible however. It is not possible to move the splitbar to make one of the panes disappear from the face of the screen.
The size of the two panes in the splitter (and thus the splitbar's range of motion) can be constrained using either CSS min-width and max-width properties on the element panes or by the options object passed to the plugin when the splitter is created. For CSS properties, use pixel (px) units so the plugin can parse them. The options object values are also numbers assumed to be in pixels.
When the plugin initializes the splitter, it creates the splitbar element that goes between the two panes. It automatically assigns the class vsplitbar to vertical splitters and hsplitbar to horizontal ones. (The splitbar class names need to be unique for vertical vs. horizontal splitbars so that nested splitters can be accomodated.) This allows you to create stylesheet rules for the splitbar. You can change the class name by passing the splitbarClass string to the plugin.
By default, when the mouse is over the splitbar it changes to a two-headed arrow cursor in the direction of motion (e-resize or n-resize). To override the default, add a cursor property to the splitbar's stylesheet entry. A custom cursor such as an .ani or .cur file from a URL can be used for special effects. See the Skinny Splitbar demo for an example of custom cursors.
Most of the options that control the behavior of the splitter plugin can be located in either of two places. You can specify them in the object passed into the plugin when the splitter is created, or in stylesheet properties for the elements used by the splitter. The descriptions below are for the names used by the options object, but if that option can also be controlled by styles it is described in that section as well.
true, the plugin will retrieve the size of that pane from the width/height stylesheet rules. Otherwise, pass in a number representing the initial size (pixels) of pane A or pane B. When the splitter container is resized, pane A is usually held at its current size and pane B grows or shrinks as a result. When initB is specified, however, the plugin attempts to keep pane B constant and pane A changes size. However, pane B may still be resized if pane A reaches a min/max size limit and pane B is not at its minimum size. If neither initA nor initB are specified, the splitbar is placed in the center of the splitter area.