Using Spry Widgets: Collapsible Panel Overview

About Spry widgets

A Spry widget is a page element containing built-in behaviors and functions that provide a richer user experience by enabling user interaction. These behaviors can 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.

The Spry framework supports a set of re-usable widgets, written in standard HTML, CSS, and JavaScript. You can easily insert these widgets—the code is HTML and CSS at its simplest—and then style the widget according to your liking.

Each widget in the Spry framework is associated with unique CSS and JavaScript files. The CSS file contains everything necessary for styling the widget, and the JavaScript file gives the widget its functionality. You must link both of these file to the page on which you want the widget to function and appear styled. otherwise the widget won’t have any functionality or styling. For more information, see the appropriate sections about linking associated files in the topics that follow.

The CSS and JS 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 Collapsible Panel widget are called SpryCollapsiblePanel.css and SpryCollapsiblePanel.js).

Anatomy of the Collapsible Panel widget

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 illustration shows a Collapsible Panel widget, expanded and collapsed.

The HTML for the Collapsible Panel widget is comprised of an outer div tag that contains the content panel and the tab container. The HTML for the Collapsible Panel widget also includes script tags in the head of the document and after the Collapsible Panel’s HTML markup.

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 markup creates a JavaScript object that makes the Collapsible Panel interactive. Following is the HTML markup for a Collapsible Panel widget:

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

In the code, you can see that the JavaScript operator new initializes the Collapsible Panel widget object, and transforms the div with the ID of cp1 from static HTML markup 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 JavaScript library, SpryCollapsiblePanel.js, that you linked in the head of the document.

You will also notice that 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 CSS file, SpryCollapsiblePanel.css.

You can change the appearance of any given part of the Collapsible Panel widget by editing the CSS that corresponds to the class names assigned to it in the HTML. For example, if you wanted to change the background color of the Collapsible Panel’s tabs, you would edit the .CollapsiblePanelTab rule in the SpryCollapsiblePanel.css file. In addition to the classes shown in the HTML markup, 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 live in the JavaScript library file, SpryCollapsiblePanel.js. 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. (In the CSS file, the behavior classes are blank by default, but you can add properties to them. ) If you want to delete the default behaviors entirely, you’ll need to delete them from the SpryCollapsiblePanel.js file.

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 an CollapsiblePanelOpen class on the currently open panel, even if there are not properties set for the CollapsiblePanelOpen class in the SpryCollapsiblePanel.css file.

Collapsible Panel Structure

In the example above, DIVs are used to create a nested tag structure.

  • Container <DIV>
    • Tab <DIV>
    • Content <DIV>

This 2 level, 3 container structure is key to the Collapsible Panel working properly; the structure is more important than the actual tags used. Spry only reads the structure and builds the Collapsible Panel accordingly. As long as that 2 level, 3 container structure is maintained, any block level element can be used to create the structure.

<div>
    <H3>Tab Label</H3>
   <p>Content Here</p>
</div>

DIVs are used because they are flexible and can contain other block level elements. Remember that, for instance, you cannot put other block level elements within a <p> tag.

CSS for the Collapsible Panel widget

The accompanying file, SpryCollapsiblePanel.css, contains the rules that style the Collapsible Panel widget. You can edit these rules to style the Collapsible Panel’s look and feel to your own liking. The names of the rules in the style sheet correspond directly to the names of the classes specified in the HTML markup.

.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;
}
      

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

The names of the behaviors CSS classes (CollapsiblePanelTabHover, CollapsiblePanelFocused, etc) at the end of the style sheet can only be changed programatically. If you don't want the appearance of the widget to change when these behaviors are invoked, simply override those rules so they don't change the appearance of the widget, or remove the rules from the SpryCollapsiblePanel.css file.

To set the height of the content container, add a CSS "height" attribute to '.CollapsiblePanelContent ' class.

Setting the height of '.CollapsiblePanel' will set the height of the whole widget, independent of the content panel size.

Using the Collapsible Panel widget

This section contains the following topics:
  • To insert a Collapsible Panel widget
  • Styling the Collapsible Panel widget

To insert a Collapsible Panel widget

Adding a Collapsible Panel to your page is pretty straightforward.

The code is simply:

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


Just make sure that the path to the scripts are correct in the <head>.

Styling the Collapsible Panel widget

The Collapsible Panel widget comes with a CSS file (SpryCollapsiblePanel.css) that provides default styling for the widget. You can, however, easily style the widget to your liking by simply changing the appropriate CSS. The CSS rules in the SpryCollapsiblePanel.css style sheet use the same class names as the related elements in the HTML, so it’s easy for you to know which CSS rules correspond to which parts of the Collapsible Panel widget. Additionally, the SpryCollapsiblePanel.css file contains class names for behaviors that are related to the widget (for example, hovering or clicking behaviors).

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

To change the appearance of the Collapsible Panel widget

  1. Open the SpryCollapsiblePanel.css file. You can find the SpryCollapsiblePanel.css file in the widgets/collapsiblepanel directory.
  2. Locate the CSS rule for the part of the Collapsible Panel that you want to change. For example, if you wanted to change the background color of the Collapsible Panel’s tabs, you would edit the .CollapsiblePanelTab rule in the SpryCollapsiblePanel.css file.
  3. Make your changes to the CSS and save the file.

If you like, you can replace style-related class names in the SpryCollapsiblePanel.css file and HTML markup with class names or your own. Doing so does not affect the functionality of the widget.

The SpryCollapsiblePanel.css file has extensive comments, explaining the code and the thought behind certain rules. Check it out for further information on styling.

Notice that the Collapsible Panel width is stored in the .CollapsiblePanel class. Content Panel height is set in the CollapsiblePanelContent class. This value should be set to ensure that panel content sizes are the same. If this rule is not present and the animation is turned off, the content panel size will be determined by the content of the panel and not the CSS.

Collapsible Panel Behaviors

The Collapsible Panel widget comes with a few predefined behaviors. These behaviors apply/remove CSS classes when a particular event occurs. For instance, when a user hovers over the tab, the CollapsiblePanelTabHover class is applied. This is similar to 'a:hover' for links. These behaviors are always applied to the Collapsible Panel. To use them, simply create rules for the style used for that behavior. If they are not wanted, simply leave the CSS blank. The behaviors are blank by default, but you can change them by adding properties and values to the rules.

To change the behaviors of the Collapsible Panel widget

  1. Open the SpryCollapsiblePanel.css file. You can find the SpryCollapsiblePanel.css file in the widgets/Collapsible Panel directory.
  2. Locate the CSS rule for the Collapsible Panel behavior that you want to change. The Collapsible Panel widget comes with four built-in rules for behaviors:

  3. CollapsiblePanelFocused This class is added to the widget's top-level element when it has keyboard focus.
    CollapsiblePanelTabHover This class is added to the widget's tab element whenever the mouse enters it. It is automatically removed when the mouse leaves the tab.
    CollapsiblePanelOpen This class is added to the widget's top-level element when the panel is showing its content area.
    CollapsiblePanelClosed This class is added to the widget's top-level element when the panel's content area is closed.

  4. Add CSS rules for any of the behaviors you wish to enable.

You cannot replace behavior-related class names in the SpryCollapsiblePanel.css file with class names of your own because the names of the CSS class used for the behaviors are hard coded as part of the Spry framework. You can however, trump the default class with your own class names by sending the new CSS class names as arguments to the Collapsible Panel constructor:

<script> 
   var cp1 = new Spry.Widget.CollapsiblePanel("Acc2", { hoverClass: "hover", openClass: "open", closedClass: "closed", focusedClass: "focused" }); 
</script> 


Keyboard Navigation

Making widgets accessible for keyboard navigation is an important part of every widget. Keyboard navigation allows the widget to be controlled via the Space Bar or Enter key. This is critical for those that can't or choose not to use the mouse.

Enabling keyboard navigation on a Collapsible Panel widget is easy. The foundation of keyboard navigation is the TabIndex attribute. This attribute tells the browser how to tab through the document.

To enable keyboard navigation on the Collapsible Panel, simply place a tabindex attribute onthe Collapsible Panel tab container tag:

<div class="CollapsiblePanel" id="cp1" >
<div class="CollapsiblePanelTab" tabIndex="0">Tab</div>
<div class="CollapsiblePanelContent">Content</div>
</div>

Keyboard navigation is now enabled. If it has a value of zero, the browser will figure out the order. If it has a positive integer value, that order value will be used. Keyboard navigation can also be enabled by wrapping the tab content with an <a>.

Panel Status

There will be instances when you will want a the panel to be open or closed when the page loads. By default, it is open. Closed can be accomplished by setting the contentIsOpen option in the constructor.

<script> 
   var cp1 = new Spry.Widget.CollapsiblePanel("cp1",{contentIsOpen:false });  
</script>


You can 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>
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>

 

Opening and Closing Panel

You can programmatically open and close the panel from Javascript using the following functions.

<button onclick="cp1.open();" >open panel</button>
<button onclick="cp1.close();">close panel</button>
<script> var cp1 = new Spry.Widget.CollapsiblePanel("cp1"); </script>


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