Working with the Collapsible Panel widget

A Spry widget is a page element that combines HTML, CSS and JavaScript data to enable user interaction. The Spry framework for Ajax supports a set of reusable widgets written in standard HTML, CSS, and JavaScript code.

About Spry widgets

A Spry widget is a page element that combines HTML, CSS and JavaScript code to enable user interaction. A Spry widget is made up of the following parts:

Widget structure
An HTML code block that defines the structural composition of the widget.
Widget behavior
JavaScript code that controls how the widget responds to user-initiated events.
Widget styling
CSS code that specifies the appearance of the widget.

The Spry framework supports a set of reusable widgets written in standard HTML, CSS, and JavaScript code. You can easily insert these widgets - the code is HTML and CSS at its simplest - and then style the widget. The behaviors in the framework include functionality that lets users show or hide content on the page, change the appearance (such as color) of the page, interact with menu items, and much more.

Each widget in the Spry framework is associated with unique CSS and JavaScript files, available on Adobe Labs. The CSS file contains everything necessary for styling the widget, and the JavaScript file gives the widget its functionality. The CSS and JavaScript files associated with a given widget are named after the widget, so it's easy for you to know which files correspond to which widgets. (For example, the files associated with the Accordion widget are called SpryAccordion.css and SpryAccordion.js).

About Spry widget accessibility and JavaScript degradation

It is critical to the usability of the widget that it be accessible when following established web navigation conventions. You can't assume that the user is using a mouse, and therefore Adobe has taken steps to ensure that all aspects of the currently available widgets are accessible through the keyboard. In the Accordion widget, for example, you can use up and down arrow keys to open content panels. Adobe encourages all widget developers to build in this kind of functionality.

It's also impossible to control the end user's environment. Adobe develops widgets to ensure that when JavaScript is turned off, all the content of the widget is still available on the screen. While this will most likely affect the page layout, it is more important that the content of the widget still be available, especially when working with disclosure widgets. Adobe ensures that default CSS states do not set visibility to hidden, and that HTML code is not positioned off screen.

Coding guidelines for developing Spry widgets

One of the goals of Spry is to enable the user community to build and share widgets. Adobe has a set of guidelines to use when authoring widgets for public distribution. Adobe is providing these guidelines with the hope that all widgets will have a consistent base functionality.

Keeping to these guidelines will help ensure that widgets are easy to understand and use, plus consistency strengthens the framework for everyone.

Using standard code is important because there is less to learn for the common user. It also makes it easy to use these widgets in WYSIWYG editors.

CSS code is used in some widgets to show and hide content by switching the visibility rule in CSS code. This is an example of a required use of CSS. Such a use is acceptable because the CSS code is the obvious mechanism for showing and hiding content. CSS code that is pure styling, however, should not be required. The widget should always function without styling. Document required CSS rules with comments in the CSS file, and if you're providing further documentation, mention it there as well.

Most widgets are activated with a single line of JavaScript code just after the actual widget code. Try to keep the JavaScript arguments to a minimum. Widths and heights of widgets should be set in CSS code, not in JavaScript, unless there are no other options.

Keyboard navigation and accessibility are important to users and to Spry. Write keyboard navigation so that users can use common workflow keys (arrow keys, space bar) to access all parts of your widget. Use things like tab order where appropriate.

It's vital that content not be hidden in non-scripting environments. Ensure that when JavaScript is turned off, your content is not hidden because of CSS visibility being turned off or content being positioned off screen.

Collapsible Panel widget overview and structure

A Collapsible Panel widget is a panel that can store content in a compact space. Users hide or reveal the content stored in the Collapsible Panel by clicking the tab of the widget. The following example shows a Collapsible Panel widget, expanded and collapsed.


A.
Expanded
B.
Collapsed

The HTML code for the Collapsible Panel widget is made up of an outer div tag that contains the content div tag and the tab container div tag. The HTML code for the Collapsible Panel widget also includes script tags in the head of the document and after the Collapsible Panel's HTML code.

The script tag in the head of the document defines all of the JavaScript functions related to the Collapsible Panel widget. The script tag after the Collapsible Panel widget code creates a JavaScript object that makes the Collapsible Panel interactive. Following is the HTML code for an Collapsible Panel widget:

<head>
...
	<!--Link the CSS style  sheet that styles the Collapsible Panel-->
	<link href="SpryAssets/SpryCollapsiblePanel.css" rel="stylesheet" 
		type="text/css" />
	<!--Link the Spry Collapsible Panel JavaScript library-->
	<script src="SpryAssets/SpryCollapsiblePanel.js" type="text/javascript"></script> 
</head> 
<body>
	<!--Create the Collapsible Panel widget and assign classes to each element-->
	<div id="CollapsiblePanel1" class="CollapsiblePanel">
		<div class="CollapsiblePanelTab">Tab</div>
		<div class="CollapsiblePanelContent">Content</div> 
	</div>
	<!--Initialize the Collapsible Panel widget object-->
	<script type="text/javascript">
		var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1");
	</script> 
</body> 

In the code, the new JavaScript operator initializes the Collapsible Panel widget object, and transforms the div content with the ID of CollapsiblePanel1 from static HTML code into an interactive page element. The Spry.Widget.CollapsiblePanel method is a constructor in the Spry framework that creates Collapsible Panel objects, and the information necessary to initialize the object is contained in the SpryCollapsiblePanel.js JavaScript library that you linked to in the head of the document.

Each of the elements in the Collapsible Panel widget contains a CSS class. These classes control the style of the Collapsible Panel widget, and exist in the accompanying SpryCollapsiblePanel.css file.

You can change the appearance of any given part of the Collapsible Panel widget by editing the CSS code that corresponds to the class names assigned to it in the HTML code. For example, to change the background color of the Collapsible Panel's tabs, edit the CollapsiblePanelTab rule in the SpryCollapsiblePanel.css file. Keep in mind that changing the CSS code in the SpryCollapsiblePanel.css file will affect all collapsible panels that are linked to that file.

In addition to the classes shown in the HTML code, the Collapsible Panel widget includes certain default behaviors that are attached to the widget. These behaviors are a built‑in part of the Spry framework, and are in the SpryCollapsiblePanel.js JavaScript library file. The Collapsible Panel library includes behaviors related to hovering, clicking (to open and close the panel), panel focus, and keyboard navigation.

You can change the look of the Collapsible Panel as it relates to these behaviors by editing the appropriate classes in the SpryCollapsiblePanel.css file. If for some reason you want to remove a given behavior, you can delete the CSS rules that correspond to that behavior.

Note: While you can change the look of the Collapsible Panel as it relates to a certain behavior, you cannot alter the built‑in behaviors themselves. For example, Spry still places a CollapsiblePanelFocused class on the currently open panel, even if no properties are set for the CollapsiblePanelFocused class in the SpryCollapsiblePanel.css file.

Variation on tags used for Collapsible Panel widget structure

In the preceding example, div tags create a nested tag structure for the widget:

Container div
	Tab div
	Content div

This 2-level, 3-container structure is essential for the Collapsible Panel widget to work properly; the structure, however, is more important than the actual tags you decide to use. Spry reads the structure (not div tags necessarily) and builds the widget accordingly. As long as the 2-level, 3-container structure is in place, you can use any block-level element to create the widget:

Container div 
	H3 tag 
	P tag

The div tags in the example are flexible and can contain other block-level elements. A p tag (or any other inline tag), however, cannot contain other block-level elements, so you cannot use it as a container or panel tag for the collapsible panel.

CSS code for the Collapsible Panel widget

The SpryCollapsiblePanel.css file contains the rules that style the Collapsible Panel widget. You can edit these rules to style the collapsible panel's look and feel. The names of the rules in the CSS file correspond directly to the names of the classes specified in the Collapsible Panel widget's HTML code.

Note: You can replace style-related class names in the SpryCollapsiblePanel.css file and HTML code with class names of your own. Doing so does not affect the functionality of the widget, as CSS code is not required for widget functionality.

The default functionality for the behaviors classes at the end of the style sheet are defined in the SpryCollapsiblePanel.js JavaScript library file. You can change the default functionality by adding properties and values to the behavior rules in the style sheet.

The following is the CSS code for the SpryCollapsiblePanel.css file:

/*Collapsible Panel styling classes*/
.CollapsiblePanel {
	margin: 0px;
	padding: 0px;
	border-left: solid 1px #CCC;
	border-right: solid 1px #999;
}
.CollapsiblePanelTab {
	font: bold 0.7em sans-serif;
	background-color: #DDD;
	border-top: solid 1px #999;
	border-bottom: solid 1px #CCC;
	margin: 0px;
	padding: 2px;
	cursor: pointer;
	-moz-user-select: none;
	-khtml-user-select: none;
}
.CollapsiblePanelContent {
	margin: 0px;
	padding: 0px;
	border-bottom: solid 1px #CCC;
}
.CollapsiblePanelTab a {
	color: black;
	text-decoration: none;
}
.CollapsiblePanelOpen .CollapsiblePanelTab {
	background-color: #EEE;
}
.CollapsiblePanelTabHover,  .CollapsiblePanelOpen .CollapsiblePanelTabHover {
background-color: #CCC;
}
.CollapsiblePanelFocused .CollapsiblePanelTab {
	background-color: #3399FF;
}

The SpryCollapsiblePanel.css file contains extensive comments, explaining the code and the purpose for certain rules. For further information, see the comments in the file.

Insert the Collapsible Panel widget

  1. Locate the SpryCollapsiblePanel.js file and add it to your web site. You can find the SpryCollapsiblePanel.js file in the widgets/collapsiblepanel directory, located in the Spry directory that you downloaded from Adobe Labs.

    For example, create a folder called SpryAssets in the root folder of your web site, and move the SpryCollapsiblePanel.js file to it. The SpryCollapsiblePanel.js file contains all of the information necessary for making the Collapsible Panel widget interactive.

  2. Locate the SpryCollapsiblePanel.css file and add it to your web site. You might choose to add it to the main directory, or to a CSS directory if you have one.
  3. Open the web page to add the Collapsible Panel widget to and link the SpryCollapsiblePanel.js file to the page by inserting the following script tag in the page's head tag:
    <script src="SpryAssets/SpryCollapsiblePanel.js" type="text/javascript"></script> 

    Make sure that the file path to the SpryCollapsiblePanel.js file is correct. This path varies depending on where you've placed the file in your web site.

  4. Link the SpryCollapsiblePanel.css file to your web page by inserting the following link tag in the page's head tag:
    <link href="SpryAssets/SpryCollapsiblePanel.css" rel="stylesheet" type="text/css" /> 

    Make sure that the file path to the SpryCollapsiblePanel.css file is correct. This path varies depending on where you've placed the file in your web site.

  5. To add the collapsible panel to your web page, insert the following div tag where you want the collapsible panel to appear on the page:
    <div id="CollapsiblePanel1" class="CollapsiblePanel">
    </div> 
  6. To add a tab to the collapsible panel, insert a div class="CollapsiblePanelTab" tag inside the div class="CollapsiblePanel" tag, as follows:
    <div id="CollapsiblePanel1" class="CollapsiblePanel">
    	<div class="CollapsiblePanelTab">Tab</div>
    </div> 
  7. To add a content area to the panel, insert a div class="CollapsiblePanelContent" tag inside the div class="CollapsiblePanel" tag, as follows:
    <div class="AccordionPanel">
    	<div class="CollapsiblePanelTab">Tab</div>
    	<div class="CollapsiblePanelContent">Content</div>
    </div> 

    Insert the content between the opening and closing CollapsiblePanelContent tags (For example, Content, as in the preceding example). The content can be any valid HTML code, including HTML form elements.

  8. To initialize the Spry collapsible panel object, insert the following script block after the HTML code for the Collapsible Panel widget:
    <div id="CollapsiblePanel1" class="CollapsiblePanel">
    . . .
    </div>
    <script type="text/javascript">
    	var acc1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1");
    </script> 

    The new JavaScript operator initializes the Collapsible Panel widget object, and transforms the div content with the ID of CollapsiblePanel1 from static HTML code into an interactive collapsible panel object. The Spry.Widget.CollapsiblePanel method is a constructor in the Spry framework that creates collapsible panel objects. The information necessary to initialize the object is contained in the SpryCollapsiblePanel.js JavaScript library that you linked to at the beginning of this procedure.

    Make sure that the ID of the collapsible panel's div tag matches the ID parameter you specified in the Spry.Widgets.CollapsiblePanel method. Make sure that the JavaScript call comes after the HTML code for the widget.

  9. Save the page.

    The complete code looks as follows:

    <head>
    ...
    <link href="SpryAssets/SpryCollapsiblePanel.css" rel="stylesheet" type="text/css" />
    <script src="SpryAssets/SpryCollapsiblePanel.js" type="text/javascript"></script>
    </head>
    <body>
    	<div id="CollapsiblePanel1" class="CollapsiblePanel">
    		<div class="CollapsiblePanelTab">Tab</div>
    		<div class="CollapsiblePanelContent">Content</div>
    	</div>
    <script type="text/javascript">
    	var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1");
    </script>
    </body>

Enable keyboard navigation

Making widgets accessible for keyboard navigation is an important part of every widget. Keyboard navigation lets the user control the widget open or close state using the arrows or user defined keys.

The foundation of keyboard navigation is the tabIndex attribute. This attribute tells the browser how to use the tabs to navigate through the document.

 To enable keyboard navigation on the collapsible panel, add a TabIndex value to the collapsible panel tab tag, as follows:
<div id="CollapsiblePanel1" class="CollapsiblePanel">
	<div class="CollapsiblePanelTab" tabIndex="0">Tab</div>
	<div class="CollapsiblePanelContent">Content</div>
</div>

If the tabIndex attribute has a value of zero (0), the browser determines the order. If the tabIndex attribute has a positive integer value, that order value is used.

To enable keyboard navigation, wrap the tab content with an a tag.

Note: Using tabIndex on a div tag is not XHTML 1.0 compliant.

You can also set custom keys for keyboard navigation. Custom keys are set as arguments of the collapsible constructor script:

<script type="text/javascript">
	var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1", {openPanelKeyCode:  34 /* PgDn key */, closePanelKeyCode: 33 /* PgUp key */});
</script>

Set the default state of the panel

By default the Collapsible Panel widget is open when the web page loads in a browser. You can, however, change the status of the panel if you want the panel to be closed when the page loads.

 Set the contentIsOpen option in the constructor as follows:
<script type="text/javascript">
	var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1", { contentIsOpen: false });
</script>

You can also check the status of the panel with the isOpen function. The following code returns true if the panel is open and false if it is not:

<script type="text/javascript">
function  getStatus(){
var xx = CollapsiblePanel1.isOpen();
document.form1.textfield.value = xx
}
</script>
</head>
<body>
<div id="CollapsiblePanel1" class="CollapsiblePanel">
  <div class="CollapsiblePanelTab" tabIndex="0" onclick="getStatus();">Tab</div>
  <div class="CollapsiblePanelContent">Content</div>
</div>
<form id="form1" name="form1" method="post" action="">
  <input name="textfield" type="text" id="textfield" value="a" size="50" />
</form>
<script type="text/javascript">
<!--
var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1");
//-->
</script>

Open the panel programatically

You can programatically open and close the Collapsible Panel widget by using JavaScript functions. For example, you might have a button on your page, that opens the collapsible panel when the user clicks the button.

 Use the following functions to open or close a collapsible panel:
<input type="button" onclick="CollapsiblePanel1.open();" >open panel</input>
<input type="button" onclick="CollapsiblePanel1.close();">close panel</input>
<script type="text/javascript">
	var CollapsiblePanel1 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel1");
</script>

Customize the Collapsible Panel widget

The SpryCollapsiblePanel.css file provides the default styling for the Collapsible Panel widget. You can, however, easily customize the widget by changing the appropriate CSS rule. The CSS rules in the SpryCollapsiblePanel.css file use the same class names as the related elements in the collapsible panel's HTML code, so it's easy for you to know which CSS rules correspond to the different sections of the Collapsible Panel widget. Additionally, the SpryCollapsiblePanel.css file contains class names for behaviors that are related to the widget (for example, hovering and clicking behaviors).

The SpryCollapsiblePanel.css file should already be included in your website before you start customizing.

Note: Internet Explorer up to and including version 6 does not support Sibling and child contextual selectors (for example, .CollapsiblePanel + .CollapsiblePanel or .CollapsiblePanel > .CollapsiblePanel).

Style a CollapsiblePanel widget (general instructions)

Set properties for the entire Collapsible Panel widget container, or set properties for the components of the widget individually.

  1. Open the SpryCollapsiblePanel.css file.
  2. Locate the CSS rule for the part of the collapsible panel to change. For example, to change the background color of the collapsible panel's tab, edit the CollapsiblePanelTab rule in the SpryCollapsiblePanel.css file.
  3. Make your changes to the CSS rule and save the file.

You can replace style-related class names in the SpryCollapsiblePanel.css file and HTML code with class names of your own. Doing so does not affect the functionality of the widget.

The SpryCollapsiblePanel.css file contains extensive comments, explaining the code and the purpose for certain rules. For further information, see the comments in the file.

Style Collapsible Panel widget text

Set properties for the entire Collapsible Panel widget container, or set properties for the components of the widget individually.

 To change the text format of a Collapsible Panel widget, use the following table to locate the appropriate CSS rule, and then add your own text styling properties and values.

Style to change

Relevant CSS rule

Example of properties and values to add or change

Text in the entire collapsible panel

.CollapsiblePanel

font: Arial; font-size:medium;

Text in panel tab only

.CollapsiblePanelTab

font: bold 0.7em sans-serif; (This is the default value.)

Text in content panel only

.CollapsiblePanelContent

font: Arial; font-size:medium;

Change Collapsible Panel widget background colors

 Use the following table to locate the appropriate CSS rule, and then add or change background color properties and values.

Color to change

Relevant CSS rule

Example of property and value to add or change

Background color of panel tab

.CollapsiblePanelTab

background-color: #DDD; (This is the default value.)

Background color of content panel

.CollapsiblePanelContent

background-color: #DDD;

Background color of tab when panel is open

.CollapsiblePanelOpen .CollapsiblePanelTab

background-color: #EEE; (This is the default value.)

Background color of open panel tab when the mouse pointer moves over it

.CollapsiblePanelTabHover, .CollapsiblePanelOpen .CollapsiblePanelTabHover

background-color: #CCC; (This is the default value.)

Constrain the width of a collapsible panel

By default, the Collapsible Panel widget expands to fill available space. To constrain the width of a Collapsible Panel widget, set a width property for the collapsible panel container.

  1. Locate the CollapsiblePanel CSS rule in the SpryCollapsiblePanel.css file. This rule defines properties for the main container element of the Collapsible Panel widget.
  2. Add a width property and value to the rule, for example width: 300px;.

Change collapsible panel height

To set the height of a collapsible panel, add a height property to the CollapsiblePanelContent rule or the CollapsiblePanel rule.

 In the SpryCollapsiblePanel.css file, add a height property and value to the CollapsiblePanelContent rule, for example, height: 300px;. Note: Setting the height of the CollapsiblePanel rule sets the height of the entire widget, independent of the content panel size.

Change collapsible panel behaviors

The collapsible panel widget includes a few predefined behaviors. These behaviors consist of changing CSS classes when a particular event occurs. For example, when a mouse pointer hovers over a collapsible panel tab, Spry applies the CollapsiblePanelTabHover class to the widget. (This behavior is similar to a:hover for links.) The behaviors are blank by default; to change them, add properties and values to the rules.

  1. Open the SpryCollapsiblePanel.css file and locate the CSS rule for the collapsible panel behavior to change. The Collapsible Panel widget includes four built-in rules for behaviors.

    Behavior

    Description

    .CollapsiblePanelTabHover

    Spry adds this class to the widget's tab element whenever the mouse enters hovers over it. The class is automatically removed when the mouse leaves the tab.

    .CollapsiblePanelOpen

    Spry adds this class to the widget's top-level element when the panel's content area is visible.

    .CollapsiblePanelClosed

    Spry adds this class to the widget's top-level element when the panel's content area is closed

    .CollapsiblePanelFocused

    Spry adds this class to the widget's top-level element when the widget has keyboard focus.

    For examples, see the collapsible panel sample file located in the samples directory of the Spry directory that you downloaded from Adobe Labs.

  2. Add CSS rules for any of the behaviors you want to enable.
Note: You cannot replace behavior-related class names in the SpryCollapsiblePanel.css file with class names of your own because the behaviors are hard coded as part of the Spry framework. To override the default class with your class name, send the new values as arguments to the collapsible panel constructor:
<script type="text/javascript">
	var CP2 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel2", { hoverClass: "hover", openClass: "open", closedClass: "closed", focusedClass: "focused" });
</script>

Turn off panel animation

By default, a collapsible panel uses animation to smoothly open and close.

 To turn off animation so that the panel instantly opens and closes, send an argument in the collapsible panel constructor, as follows:
<script type="text/javascript">
	var CP5 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel5", { enableAnimation: false });
</script>

Set panel animation timing

You can change the time it takes for a panel to open. Set the time in milliseconds (1000 = 1 second). By default, Spry uses 500 milliseconds.

 Add the duration option to the constructor:
<script type="text/javascript">
	var CP9 = new Spry.Widget.CollapsiblePanel("CollapsiblePanel9", { duration: 100 });
</script>

Copyright © 2006. Adobe Systems Incorporated. All rights reserved.