Home

Awesome

Overview

The Expander Plugin hides (collapses) a portion of an element's content and adds a "read more" link so that the text can be viewed by the user if he or she wishes. By default, the expanded content is followed by a "read less" link that the user can click to re-collapse it. Expanded content can also be re-collapsed after a specified period of time. The plugin consists of a single method, .expander(), with a bunch of options.

Features

Options

The following options, shown here with their default values, are currently available:

// the number of characters at which the contents will be sliced into two parts.
slicePoint: 100,

// a string of characters at which to slice the contents into two parts,
// but only if the string appears before slicePoint
// Useful for slicing at the first line break, e.g. {sliceOn: '<br'}
sliceOn: null,

// whether to keep the last word of the summary whole (true) or let it slice in the middle of a word (false)
preserveWords: true,

// whether to normalize the whitespace in the data to display (true) or not (false)
normalizeWhitespace: true,

// whether to count and display the number of words inside the collapsed text
// This will either allow or prevent the word count
// (and thus the configurable wordCountText) from showing.
showWordCount: false,

// text to include between summary and detail. Default ' ' prevents appearance of
// collapsing two words into one.
// Was hard-coded in script; now exposed as an option to fix issue #106.
detailPrefix: ' ',

// what to display around the counted number of words, set to '{{count}}' to show only the number
wordCountText: ' ({{count}} words)',

// a threshold of sorts for whether to initially hide/collapse part of the element's contents.
// If after slicing the contents in two there are fewer words in the second part than
// the value set by widow, we won't bother hiding/collapsing anything.
widow: 4,

// text displayed in a link instead of the hidden part of the element.
// clicking this will expand/show the hidden/collapsed text
expandText: 'read more',
expandPrefix: '&hellip; ',

// class names for summary element and detail element
summaryClass: 'summary',
detailClass: 'details',

// one or more space-separated class names for <span> around
// "read-more" link and "read-less" link
moreClass: 'read-more',
lessClass: 'read-less',

// number of milliseconds after text has been expanded at which to collapse the text again.
// when 0, no auto-collapsing
collapseTimer: 0,

// effects for expanding and collapsing
expandEffect: 'slideDown',
expandSpeed: 250,
collapseEffect: 'slideUp',
collapseSpeed: 200,

// start with the details expanded (and the "read-less" link showing)
startExpanded: true,

// allow the user to re-collapse the expanded text.
userCollapse: true,

// text to use for the link to re-collapse the text
userCollapseText: 'read less',
userCollapsePrefix: ' ',


// all callback functions have the this keyword mapped to the element in the jQuery set when .expander() is called

onSlice: null, // function() {},
beforeExpand: null, // function() {},
afterExpand: null, // function() {},
onCollapse: null // function(byUser) {},
afterCollapse: null // function() {}

Known Issues

Workarounds for inherent issues

  1. Add a JS script in the head that will add a "js" class to the html element (see http://www.learningjquery.com/2008/10/1-way-to-avoid-the-flash-of-unstyled-content/). This is done by JavaScript so that the element will not be hidden for clients with their JavaScript disabled/inoperable.

  2. Add the following somewhere in your CSS (using your own class names):

    .js .myexpander.js-myexpander-hidden {
      display: none;
    }
    
  3. Add a JS script that will execute later (bottom of body or within $(document).ready()):

    $('.myexpander').expander().removeClass('js-myexpander-hidden');
    

    a. If you still see a little "flash" of unstyled content, add this script to remove the class in an onSlice callback:

    $(.myexpander).expander({
      onSlice: function() {
        $(this).removeClass('js-myexpander-hidden');
      }
    });
    

Injecting with CommonJS or AMD

// CommonJS
var jQuery = require('jquery');
require('jquery-expander')(jQuery);

// AMD
define(['jquery', 'jquery-expander'], function (jQuery, expander) {
  expander(jQuery)
})

Demo

A demo is provided in the repo's demo directory. Feel free to take the plugin for a spin at kswedberg.github.io/jquery-expander/demo/

Tests

The Expander Plugin comes with a set of unit tests to ensure that it is working as expected. You can run these tests online at kswedberg.github.io/jquery-expander/test/ or locally from the repo's test directory.

License

This plugin is free of charge and licensed under the MIT license.