jQuery Collapse
A lightweight and flexible jQuery plugin that allows you to collapse content. A feature also known as 'progressive disclosure'.
jQuery Collapse is tested against the latest version of jQuery but requires at least jQuery 1.7.0.
Features
- WAI ARIA compliant
- Lightweight (~1.2kb minified and gzipped)
- Cross Browser compliant (Tested in >= IE6, Firefox, Safari, Chrome, Opera)
- Accordion behaviour can be enabled.
- Persistence to remember open sections on page reload!
Demo
A demo showcasing all the features of the plugin can be found at 'demo/demo.html' in this repository.
Usage
Load jQuery and the jQuery Collapse plugin into your document:
Here's some sample HTML markup:
Fruits Apple Pear Orange Info You can use any container you like (in this case a div element)
That's it! The data-collapse attribute will automatically trigger the script.
Open/Collapse section by default
The standard behaviour is to collapse all the sections on page load. If you want to show a section to the user on page load you can achieve this by adding an 'open' class to the section heading
I'm open by default Yay
Open all sections
You can open or close sections by utilizing events. Assume you have the following markup:
Section 1 I'm first Section 2 I'm second/p>
You can now trigger events on the elements you want to affect. For instance:
// Open all sections // Close all sections // Open first section
For further information, please refer to the events documentation.
JavaScript usage
If you'd rather omit the 'data-collapse' attribute in the HTML and load the plugin via jQuery, you can:
;
If you don't want to use the jQuery ($) wrapper, you can also access the plugin with vanilla JavaScript:
// options...;
Using custom markup
By default the plugin will look for groups of two elements. In real life™ your markup may vary and you'll need to customize how the plugin interprets it. For example
Summary details... Summary details...
In order for the plugin to understand the above markup, we can pass a 'query' option specifying where to find the header/summary element of a section:
query: 'div h2';
External markup example
You can also just use an arbitrary link on a page to collapse\expand a section:
Toggle section Summary details...
Then attach an event handler to your link and make use of jQuery Collapse events to toggle the section:
;
Custom click query
Sometimes you want to customize what element inside the collapse summary that should trigger the open/close action. Consider the following markup:
Google.com info Find stuff on google Twitter.com info Tweet stuff on twitter
Now use the clickQuery option to trigger the action only when the span is clicked
;
Accordion
To activate the accordion behaviour set 'accordion' as the value of the 'data-collapse' attribute:
...
Persistence
By default, if the user reloads the page all the sections will be closed. If you want previously collapsed sections to stay open you can add 'persist' to the data-collapse attribute:
...
And include the storage module in your document after the other scripts.
As in the example above, the target element (#demo) will require an ID in order for the persistence to work.
You can combine the accordion and persistence options by adding both values to the data-collapse attribute:
...
jQuery Collapse uses HTML5 localStorage if available, otherwise it will attempt to use cookies (read about IE support below). If that also fails, it will degrade to work but without any persistence.
Internet Explorer =< 7 Support
For IE 6-7 you'll need to include the cookie storage and JSON2 libraries for the cookie storage support to work properly:
<!--[if lt IE 8]> <script src="jquery.collapse_cookie_storage.js"></script> <script src="json2.js"></script><![endif]-->
API Documentation
Here are the exposed options and events that you can play around with using JavaScript. Enjoy.
Options
You can pass the following options when initializing the plugin with JavaScript.
- open (function) : Custom function for opening section (default: function(){ this.show() })
- close (function) : Custom function for collapsing section (default: function(){ this.hide() })
- accordion (bool) : Enable accordion behaviour by setting this option to 'true'
- persist (bool) : Enable persistence between page loads by setting this option to 'true'
- query (string) : Please refer to to using custom markup
- clickQuery (string): Please refer to custom click query
Example usage of options:
// Initializing collapse plugin// with custom open/close methods,// persistence plugin and accordion behaviour;
Events
Binding events
You can listen for the opened and closed events on a collapsed collection.
; ;
Triggering events
You can manually trigger an open, close or toggle event to change the state of a section:
// open all sections // close all sections // toggle last section
When a section changes state, it will trigger either an "opened" or "closed" event in return, depending on it's new state.
API methods
If you're using vanilla JavaScript to instantiate the plugin, you'll get direct access to the open, close and toggle methods.
var demo = ; // Initializing plugindemo; // Open all sectionsdemo; // Close all sectionsdemo; // Open first sectiondemo; // Open second sectiondemo; // Close first sectiondemo; // Toggle second section
Contributing
Did you find a bug? Do you want to introduce a feature? Here's what to do (in the following order)
- Clone this repository, and run
npm install
- Write a test case
- Watch it fail (red light)
- Fix bug / introduce feature
- Watch it pass (green light)
- Refactor / Perfectionize!
- Submit a pull request on Github and wait patiently...
- Rejoice!
A note about testing
To run the tests simply type "npm test". The Karma test runner will open Chrome and Firefox and run the tests.
The tests are written in a BDD fashion using CoffeeScript and can be found in the test directory.
The test suite uses Mocha (test framework), Chai (exceptions) and Sinon (stubs and mocks).