Collapsorz 1.1

Summary

Collapsorz provides an easy way to toggle on and off children elements of an object. You can customize many aspects of what and how the expanding and collapsing works, so this fits a variety of needs and scenarios.

Updates

April 22, 2009: Collapsorz 1.1 is now available. This version adds the wrapLink option, which allows you to specify custom HTML to be wrapped around the toggle link.

December 15, 2008: Collapsorz project is now hosted at Google Code!

November 11, 2008: Collapsorz version 1.0 is released to the public.

Basic Usage

$(element).collapsorz();

$(element).collapsorz({ options });

Available Options

toggle (optional)

Selector for the elements inside the parent object that you wish to toggle. If not specified, it will toggle direct children of the selected object.

minimum (optional)

Minimum number of elements to show when collapsed. Defaults to 5 if not specified.

showText (optional)

This text will be used for the expand link. Defaults to Show if not specified.

hideText (optional)

This text will be used for the collapse link. Defaults to Hide if not specified.

linkLocation (optional)

This determines if the expand/collapse link will be displayed before or after the selected object. You can choose one of the following settings:

• after—Places the link after the selected object. This is the default setting if not specified.
• before—Places the link before the selected object.

defaultState (optional)

This determines if the object should be expanded or collapsed by default. You can choose one of the following settings:

• collapsed—Object will be collapsed by default. This is the default setting if not specified.
• expanded—Object will be expanded by default.

wrapLink (optional)

This allows you to specify some custom HTML to wrap around the link that will be created.

Examples

Default settings

<ul>
  <li>This</li>
  <li>is</li>
  <li>an</li>
  <li>unordered</li>
  <li>list</li>
  <li>and</li>
  <li>lists</li>
  <li>are</li>
  <li>good</li>
</ul>

<script type="text/javascript">
  $("ul").collapsorz();
</script>

Custom children toggling

<dl>
  <dt>Main point</dt>
    <dd>Secondary point</dd>
  <dt>Main point</dt>
    <dd>Secondary point</dd>
    <dd>Secondary point</dd>
  <dt>Main point</dt>
    <dd>Secondary point</dd>
</dl>

<script type="text/javascript">
  $("dl").collapsorz({
    toggle: "dd",
    minimum: 0,
    showText: "Show secondary points",
    hideText: "Hide secondary points"
  });
</script>

Expanded by default, with preceding styled link wrapped with custom element

<style type="text/css">
  a.collapsed { background: url(collapsed.png) left center ↵
  no-repeat; padding-left: 15px; }
  a.expanded { background: url(expanded.png) left center ↵
  no-repeat; padding-left: 15px; }
</style>

<ul>
  <li>The</li>
  <li>link</li>
  <li>should</li>
  <li>have</li>
  <li>some</li>
  <li>special</li>
  <li>styling</li>
</ul>

<script type="text/javascript">
  $("ul").collapsorz({
    minimum: 3,
    showText: "Expand list",
    hideText: "Collapse list",
    linkLocation: "before",
    defaultState: "expanded",
    wrapLink: '<div class="linkWrapper"></div>'
  });
</script>

Additional Notes

• If the number of children items is greater than or equal to the minimum number specified, the script will just skip over the object. This means no expand/collapse link will be displayed or associated with the object.
• The expand/collapse link gets a class of toggler by default.
• Depending on the state of the object, the expand/collapse link will also have a class of either collapsed or expanded, which means you can work up some styling magic on the link for the different states.