Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A jQuery plugin to toggle a panel and remember its position

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 examples
Octocat-spinner-32 README.markdown
Octocat-spinner-32 jquery.cookie.js
Octocat-spinner-32 jquery.persistentpanel.js
README.markdown

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.

Usage Examples

(See examples/index.html)

Options

Setting Name Default Value Valid Values Description
changeTogglerContents true true
false
Whether to replace the contents of your specified toggler element with the contents of togglerContentsOpen and togglerContentsClosed when it your panel is opened and closed, respectively. If you set this to false, the togglerContents settings will not be used and the toggler element's contents will not be modified.
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:
  • Your duration setting will be passed to this function
  • 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.
defaultState 'open' 'open'
'closed'
If no cookie is set, should the panel start out open or closed?
openDirection 'down' 'up'
'down'
'left'
'right'
Is used to determine default values for openFunction, closeFunction, togglerContentsOpen and togglerContentsClosed. 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:
  • Your duration setting will be passed to this function
  • 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 Which element, when clicked, should open and close your panel?
togglerClassClosed 'closed' Any valid CSS class name When your toggler is clicked and the panel closes, this class will be applied to the toggler. You could use it to change a background image, for example.
togglerContentsClosed (unicode arrow - depends on openDirection) Any HTML When your toggler is clicked and the panel closes, the toggler's contents will be replaced with this, unless changeTogglerContents is false.
togglerClassOpen 'open' Any valid CSS class name When your toggler is clicked and the panel opens, this class will be applied to the toggler. You could use it to change a background image, for example.
togglerContentsOpen (unicode arrow - depends on openDirection) Any HTML When your toggler is clicked and the panel opens, the toggler's contents will be replaced with this, unless changeTogglerContents is false.
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:
  • Accept cookieName as a parameter, so that the panel can request the correct cookie for itself
  • 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();

Something went wrong with that request. Please try again.