Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
239 lines (223 sloc) 10 KB

PersistentPanel - the panel that won't quit

A simple jQuery plugin for creating panels that remember whether they are open or closed. Allows custom animations but has sensible defaults.

  • Creates a panel that opens and closes, vertically or horizontally, when a toggler element is clicked
  • Remembers last state a user left the panel in and use that on page reload
  • Easy to use with defaults - just $('#somediv').persistentPanel();
  • You can pass in custom animations, cookie names, etc.

Warning

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.

Usage Examples

(See examples/index.html)

Options (as of v1.30)

Setting NameDefault ValueValid ValuesDescription
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:
  1. Your duration setting will be passed to this function
  2. On page load, if the panel should be closed, this function will be called with a duration of 0 (meaning "close instantly").
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'
  1. 'open'
  2. 'closed'
If no cookie is set, should the panel start out open or closed?
openDirection 'down'
  1. 'up'
  2. 'down'
  3. 'left'
  4. 'right'
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:
  1. Your duration setting will be passed to this function
  2. On page load, if the panel should be open, this function will be called with a duration of 0 (meaning "open instantly").
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'}
  1. false
  2. Object with properties 'open' and/or 'closed' - values can be any valid CSS class name
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)
  1. false
  2. {open: 'someHTML'}
  3. {closed: 'someHTML'}
  4. {open: 'someHTML', closed: 'someHTML'}
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:
  1. Accept cookieName as a parameter, so that the panel can request the correct cookie for itself
  2. Return the string value of the cookie
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:
  • Accept cookieName as the first parameter, so that the panel can set the correct cookie for itself
  • Accept value as the second parameter, so that the panel can indicate whether it should be set to 'open' or 'closed'

nonPersistentPanel() - Everything except persistence

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.