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.

This plugin is free of charge and licensed under the MIT license. As a courtesy to GPL-licensed projects that may wish to include the plugin, it is also licensed under the GPL license.

If you like the plugin and you're feeling generous, you may want to surprise me with something from my amazon.com wish list.

Quick Start Guide

Add HTML markup to your page for elements that you want to be expandable. For example:


  <div class="expandable">
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed dot eiusmod tempor
     incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
     exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor.
    </p>
    <p>Reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
    Excepteur sint occaecat cupidatat non proident, sunt inre culpa qui
    officia deserunt mollit anim id est laborum.
    </p>
  </div>

Include the jQuery core file and the Expander plugin in your document. After these scripts are referenced, you can reference a custom script file to modify the expandable elements. You may, of course, name this custom file anything you wish and place it anywhere on your server. It is named custom.js here and placed in the "scripts" directory for demonstration purposes only.

<script src="jquery.js"></script>
<script src="jquery.expander.js"></script>

<script src="/scripts/custom.js"></script>

In your custom script, select the elements you want to expand/collapse and call the .expander() method, with or without options.


// you can override default options globally, so they apply to every .expander() call
$.expander.defaults.slicePoint = 120;

$(document).ready(function() {
  // simple example, using all default options unless overridden globally
  $('div.expandable p').expander();

  // *** OR ***

  // override default options (also overrides global overrides)
  $('div.expandable p').expander({
    slicePoint:       80,  // default is 100
    expandPrefix:     ' ', // default is '... '
    expandText:       '[...]', // default is 'read more'
    collapseTimer:    5000, // re-collapses after 5 seconds; default is 0, so no re-collapsing
    userCollapseText: '[^]'  // default is 'read less'
  });

});

Known Issue

See API / Options for more ways to customize the behavior and appearance of the expander.

A couple people have reported (in issue #24) that after repeatedly expanding and collapsing some text the plugin appears to cause IE9 (and possibly older IEs) to crash. Since the plugin itself doesn’t do much when expanding/collapsing, my hunch (confirmed by one of the reporters) is that the crash has to do with animating the opacity of elements. I haven’t been able to reproduce the problem on my machine, which leads me to believe that certain graphics settings in Windows must also be contributing to the bug.

I’m not sure what the long-term fix will be, but if you need an immediate fix, you’ll need to set options for expandEffect and collapseEffect, as well as, possibly, expandSpeed and collapseSpeed.

Workaround 1: use these options in your call to .expander(), along with any others you might want, to make the text expand and collapse with no transition:


{
  expandEffect: 'show',
  expandSpeed: 0,
  collapseEffect: 'hide',
  collapseSpeed: 0
}

Workaround 2: use a “sliding” transition with these options in your call to .expander(), along with any others you might want:


{
  expandEffect: 'slideDown',
  collapseEffect: 'slideUp'
}

Expander Plugin API / Options

The Expander Plugin API provides a single method with a few options.

expander(options): Truncates an element's visible content at a specified location, collapsing the rest and allowing the user to expand it if he or she wishes.

$.expander.defaults = {
  // 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 content to display (true) or not (false)
  normalizeWhitespace: true,

  // whether to count and display the number of words inside the collapsed text
  showWordCount: false,

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

  // 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: ' ',

  // widow: 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: '… ',

  // 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: 'fadeIn',
  expandSpeed: 250,
  collapseEffect: 'fadeOut',
  collapseSpeed: 200,

  // 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() {}
};

Download

The Expander Plugin is available at the GitHub repo: /github.com/kswedberg/jquery-expander.

The plugin comes with a set of unit tests to ensure that it is working as expected.

Please report bugs on the repo's issue tracker.

‹‹ homejQuery Expander Plugin

Overview

Quick Start Guide

Known Issue

Expander Plugin API / Options

Download