PersistentPanel is a project mainly written in JavaScript, it's free.
A jQuery plugin to toggle a panel and remember its position
A simple jQuery plugin for creating panels that remember whether they are open or closed. Allows custom animations but has sensible defaults.
Despite wanting to use semantic versioning, I jumped the gun on going to 1.0, which should mean "ready for the public to use and will have no backwards-incompatible changes in the API until version 2.0." I thought I was at this point, but I continue to find things I want to tweak in the API. Since I don't want to move rapidly through 2.0, 3.0, etc, I'm just warning you here that this will be unstable until 2.0.
At that point, I plan to begin using semantic versioning properly, with patch, minor and major version changes following the numeric scheme linked above.
My apologies for any confusion.
(See examples/index.html)
| Setting Name | Default Value | Valid Values | Description |
|---|---|---|---|
| closeFunction | (depends on openDirection) | Any jquery animation for hiding |
If you don't specify this, a default will be chosen based on the
openDirection (which also has its own default). If you do specify a
closeFunction, it should accept a duration parameter. This is for two
reasons:
|
| cookieName | 'persistentPanel' | Any string | The name of the cookie to set and check for this panel. If two panels use the same cookie name (and if neither of them has this options specified, they will both use the default), toggling one of them will affect whether the other is open or closed on page load. If you have a single panel that you display on multiple pages, it should use the same cookie name on each page. |
| clickArea | (the toggler element) | Any valid jQuery selector string | Which element, when clicked, should open and close your panel? Normally, this will be determined by the toggler setting, but in some cases, you might want to specify a different area. For example, you want the toggler contents to change from one arrow to another when the panel opens and closes, but you want to place that arrow inside a larger tab, and you want the user to be able to click anywhere in the tab to toggle the panel. If you don't pass anything in for this option, the click listener is attached to the toggler itself. |
| defaultState | 'closed' |
|
If no cookie is set, should the panel start out open or closed? |
| openDirection | 'down' |
|
Is used to determine default values for openFunction, closeFunction, togglerContents.open and togglerContents.closed. If you provide your own values for all of those, this setting does nothing. (Note: opening 'up' and 'left' is currently identical to opening 'down' or 'right'.) |
| openFunction | (depends on openDirection) | Any jquery animation for showing |
If you don't specify this, a default will be chosen based on the
openDirection (which also has its own default). If you do specify an
openFunction, it should accept a duration parameter. This is for two
reasons:
|
| duration | 500 | Any number accepted by jQuery's animate functions | Duration (in milliseconds) that your openFunction and closeFunction should take to run. |
| toggler | '#panelToggler' | Any valid jQuery selector string | By default, which element, when clicked, should open and close your panel? With default settings, the toggler will both be the click trigger for the panel to open and close, and will contain a directional arrow which changes directions when the panel is opened or closed. Both of these behaviors can be overridden: if you set togglerContents to false, the arrows won't change, and if you set clickArea to something else, the click listener won't be attached to this element. Note: I **strongly** recommend that you use an ID for this selector; you may have more than one panel on the screen at some point, and you don't want multiple togglers to affect the same panel. (If you're using the same ID more than once per page, you're Doing It Wrong.) |
| togglerClass | {open: 'open', closed: 'closed'} |
|
When your toggler is clicked and the panel opens or closes, the class specified here will be applied to the toggler. If you only specify one of the classes, the other will use the default. These classes could be used to change a background image, for example, instead of changing the togglerContents. If this option is set to false, the toggler's class will not be changed. |
| togglerContents | (unicode arrows - depends on openDirection) |
|
If set to false, the contents of your toggler element will not be
modified when your toggler is opened and closed (on page load,
the toggler is immediately either opened or closed.)
If set to an object containing the keys 'open', 'closed' or both,
the contents of the toggler will be replaced with the value of the
corresponding key when the toggler is opened or closed. If one option
is not specified, it will be filled in from the defaults, based on the
openDirection. For example, if your openDirection is 'down', and you pass in togglerContents: {closed: 'open me!'}, then when your panel is closed, the toggler will contain 'open me!', and when your panel is open, it will contain the default up arrow. |
| getCookie | function(cookieName) {return $.cookie(cookieName);} |
A function to get the cookie from the cookieName option - see description |
By default, this function uses the jQuery.cookie plugin. If you
don't want this dependency, pass in your own function. It should:
|
| setCookie | function(cookieName, value) {$.cookie(cookieName, value, { expires: 30, path: '/'});} |
A function to set the cookie in the cookieName option - see description |
By default, this function uses the jQuery.cookie plugin. If you
want to customize what it does - for example, set a domain for
your cookie - refer to the jQuery.cookie plugin documentation in
the source code. It is quite well-written. For example, you could pass in the following: function(cookieName, value) {$.cookie(cookieName, value, { expires: 7, path: '/', domain: 'jquery.com', secure: true});}
If you don't want the dependency on jQuery.cookie, pass in your own function. It should:
|
If you want to use the other functionality of persistentPanel - the animation, the toggler contents, etc - but do NOT want your panel to remember its state when the page is reloaded, it's easy: call $('#someElement').nonPersistentPanel();
I don't expect anybody to install this script just to use nonPersistentPanel(); what it does could be accomplished with a pretty simple toggle function. But if you're already using persistentPanel, this lets your panels that don't need cookies use a shorter syntax that looks more like the ones that do.
Under the hood, all it does is call persistentPanel() with its options, overriding the setCookie and getCookie functions to do nothing.