type: widget

realease: 1.5

status: complete

documentation: http://docs.jquery.com/UI/Accordion

demo: http://jqueryui.com/demos/accordion

 

 

---

 

1 - Description:

 

An expandable/collapsible content pane. Applicable when content must be displayed within limited space. Accordions are most commonly seen in the stacked vertical style on the web, but a horizontal accordion, where clickable tabs are rotated 90 degress to the left, should also be considered (see a good example at Boston University's site: http://www.bu.edu/).  We'd need to determine how to display the text for a horizonal accordion since rotating text is not possible in HTML and stacking each letter of the label on a separate line looks odd.

 

An accordion doesn't allow more than one content panel to be open at the same time, and it takes a lot of effort to do that. If you are looking for a widget that allows more than one content panel to be open, don't use this.  

 

 

---

 

2 - Visual Design:

 

 

---

 

 

3 - Functional Specifications/Requirements:

 

An accordion consists of a list of header/content pairs. Headers are always visible, while at most one content panel is visible. Switching between content panels works by clicking headers or navigating with the keyboard - when the accordion has focus, key up/down change focus between headers, enter activates the content of the selected header.

 

• options:
  • active (string[selector], element, integer, default: 0)
    • when collapsible: true, activate(false) closes the accordion, otherwise nothing happens
  • autoHeight (boolean, default: true)
    • all content panels get the height of the biggest panel
    • can't be mixed with fillSpace or clearStyle
  • animated ('slide', 'bounceslide', easing method (anything in jQuery.easing) or false, default: 'slide')
  • clearStyle (boolean, default: false)
    • clears styles after animating
    • not compatible with autoHeight and fillSpace
  • collapsible (boolean, default: false)
    • there can be only one panel open at once; for collapsible:true, all panels can be closed, otherwise exactly one must be open
  • event (string, default: 'click')
    • "mouseover" changes the accordion to a hover accordion (probably the only useful alternative)
  • fillSpace (boolean, default: false)can't be mixed with autoHeight or clearStyle
    • all content panels get a fixed height, so that the accordion fills the space available
    • useful in a layout where the accordion parent element has a fixed height
  • header (string, default: '> li > :first-child,> :not(li):even')
    • must be a selector that applies to the accordion container element, via .filter()
    • the default covers both ul/li accordions, as well as flat structures like dl/dt/dd
  • icons (hash)
    • refers to CSS classes that much match an icon as defined by UI CSS framework:
      • header (string, default: 'ui-icon-triangle-1-e')
      • headerSelected (string, default: 'ui-icon-triangle-1-s')
  • navigation (boolean, default : false)
    • when enabled, searches for anchors inside the accordion (both headers and contents) and filters by their href-attribute, compared to the locaition.href
    • for the first match, the containing panel is activated
  • navigationFilter (function, default: function() { return this.href.toLowerCase() == location.href.toLowerCase(); })
    • only relevant for navigation:true
• methods:
  • accordion('activate', string[selector], element, integer)
    • same arguments and effect as active option
• callbacks:
  • changestart (event: click)
    • triggered directly after the click on a header
  • change (event: none)
    • triggered after the accordion animation is completed
• 'ui' object:
  • newHeader (object[jQuery])
  • oldHeader (object[jQuery])
  • newContent (object[jQuery])
  • oldContent (object[jQuery])

 

---

 

4 - Markup & Style:

 

4.1 Initial markup examples

 

<div id="accordion">
       <h3><a href="#">Accordion Header 1</a></h3>
       <div>Accordion Content 1</div>
       <h3><a href="#">Accordion Header 2</a></h3>
       <div>Accordion Content 2</div>
       <h3><a href="#">Accordion Header 3</a></h3>
       <div>Accordion Content 3</div>
  </div>  <dl>
       <dt><a href="#">Accordion Header 1</a></dt>
  
        <dd>Accordion Content 1</dd>
  
        <dt><a href="#">Accordion Header 2</a></dt>      <dd>Accordion Content 2</dd>
  
        <dt><a href="#">Accordion Header 3</a></dt>
  
        <dd>Accordion Content 2</dd>
  
   </dl>  <ul id="accordion">
  
        <li>
  
             <h2><a href="#">Accordion Header 1</a></h2>
  
             <div>Accordion Content 1
  
                  <ul>
  
                       <li>Some list item</li>
  
                       <li>Some list item</li>
  
                  </ul>
  
             </div>
  
        </li>
  
        <li>           <h2><a href="#">Accordion Header 2</a></h2>
  
             <div>Accordion Content 2</div>
  
        </li>
  
        <li>
  
             <h2><a href="#">Accordion Header 3</a></h2>
  
             <div>Accordion Content 2</div>
  
        </li>
  
   </ul>

4.2 Recommended transformed HTML markup demo with html and css:

 

http://jquery-ui.googlecode.com/svn/trunk/tests/static/accordion/default.html

http://jquery-ui.googlecode.com/svn/trunk/tests/static/accordion/dl.html

http://jquery-ui.googlecode.com/svn/trunk/tests/static/accordion/ul.html

 

4.3 Markup & style browser QA status

 

As of 12/12/08, static markup for this widget renders correctly in the following browsers.  (Correct rendering = true to design, with only small differences across browsers owing to differences in support of rounded corners, and native OS form element and font rendering.)

 

Please update this list as more browsers / platforms are tested.

 

	XP	Vista	Mac 10.5
IE 6
IE 7
IE 8 beta
Firefox 2.0.0.18
Firefox 3.0.4
Safari 3.2
Opera 9.1
Opera 9.62
Chrome 1.0

 

 

 

 

 

 

 

 

 

 

 

 

 

 

4.4 Accessibility recommendation

 

     Q: how accessible is the current version?

 

4.5 CSS & Theme (cascades from framework css)

---

 

5 - Latest version of plugin:

http://jquery-ui.googlecode.com/svn/trunk/demos/accordion/default.html

 

---

 

6 - Open issues being discussed

 

There are two modifications worth discussing.

 

1. Cookie persistence: http://dev.jqueryui.com/ticket/3613
2. Event handling via hoverintent: http://dev.jqueryui.com/ticket/3614

 

Both heavily affect interaction: Cookie persistence makes the accordion remember its own state across pages or page reloads, hoverintent enables a much better interaction then both click and mouseover events, and in combination with click, still works on systems like the iPhone.

 

     3. The accordion headers need 3 elements: container, icon span, and text container. Can we assume the container (h3 in the example above), and text container will be provided in initial markup? Should the text container always be an anchor for accessibility? How does the current plugin enforce these things?

 

Considering that autoHeight, fillSpace and clearStyle are all exclusive, they should probably be merged into a single option with enumerated values, eg. height: "auto", "fill", "clear".

 

The navigation and navigationFilter options are specialized active-variants, without reusing any of the existing infrastructure. A high price for a small value.

 

The active-option and the activate-method do the same thing - the method could be removed in favor of the option.

---