Using Spry Widgets: Tabbed Panel Overview

About Spry widgets

A Spry widget is a page element containing built-in behaviors 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 appear, 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 Tabbed Panel widget are called SpryTabbedPanel.css and SpryTabbed Panel.js).

Anatomy of the Tabbed Panel widget

A Tabbed Panel widget is a set of panels that can store content in a compact space. Users hide or reveal the content stored in the Tabbed Panel by clicking the tab of the panel they want to access. The panels of the Tabbed Panel open accordingly as the user clicks different tabs. In a Tabbed Panel, only one content panel is open at a given time. The following illustration shows a Tabbed Panel widget, with the third panel expanded:

The HTML for the Tabbed Panel widget is comprised of:

  • An outer div tag that contains all of the panels
  • A <ul> for the tabs
  • A div to contain the content panels
  • A div for each content panel.

The HTML for the Tabbed Panel widget also includes script tags in the head of the document and after the Tabbed Panel’s HTML markup.
The script tag in the head of the document defines all of the JavaScript functions related to the Tabbed Panel widget. The script tag after the Tabbed Panel widget markup creates a JavaScript object that makes the Tabbed Panel interactive. Following is the HTML markup for a Tabbed Panel widget:

<head>
   <link href="includes/SpryTabbedPanel.css" rel="stylesheet" type="text/css" />
   <script src="includes/SpryTabbedPanel.js"></script>
</head>
<body>
<div id="TabbedPanels1" class="TabbedPanels">
<ul class="TabbedPanelsTabGroup">
   <li class="TabbedPanelTab" tabindex="0">Tab</li>
   <li class="TabbedPanelTab" tabindex="0">Tab</li>
</ul>
<div class="TabbedPanelsContentGroup">
  <div class="TabbedPanelContent">Content</div>
  <div class="TabbedPanelContent">Content</div>
</div>
</div>
<script>
      var TabbedPanels1 = new Spry.Widget.TabbedPanels("TabbedPanels1");
</script>
</body>

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

You’ll also notice that each of the elements in the Tabbed Panel widget contains a CSS class. These classes control the style of the Tabbed Panel widget, and exist in the accompanying CSS file, SpryTabbedPanel.css.

You can change the appearance of any given part of the Tabbed 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 Tabbed Panel’s tabs, you would edit the .TabbedPanelsTab rule in the SpryTabbedPanel.css file. In addition to the classes shown in the HTML markup, the Tabbed 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, SpryTabbedPanel.js. The Tabbed Panel library includes behaviors related to hovering, tab clicking (to open panels), panel focus, and keyboard navigation.

You can change the look of the Tabbed Panel as it relates to these behaviors by editing the appropriate classes in the SpryTabbedPanel.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 SpryTabbedPanel.js file.

Note: While you can change the look of the Tabbed Panel as it relates to a certain behavior, you cannot alter the built-in behaviors themselves. For example, Spry still places an TabbedPanelFocused class on the currently open panel, even if there are not properties set for the TabbedPanelFocused class in the SpryTabbedPanel.css file.

Tabbed Panel Structure

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

  • Container <DIV>
    • Tabs <UL>
      • Tab <LI>
    • Content Container <DIV>
      • Content <DIV>

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

  • Container <DIV>
    • Tabs <DIV>
      • Tab <H3>
    • Content Container <DIV>
      • Content <P>

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 Tabbed Panel widget

The accompanying file, SpryTabbedPanel.css, contains the rules that style the Tabbed Panel widget. You can edit these rules to style the Tabbed 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.

You can replace style-related class names in the SpryTabbedPanel.css file and HTML markup with class names or your own.

The behaviors classes at the end of the style sheet are blank by default. Their default functionality is defined in the JavaScript library file SpryTabbedPanel.js. You can change the default functionality by adding properties and values to the blank behavior rules in the style sheet. If you want to eliminate the default behaviors completely, you’ll need to delete them from the SpryTabbedPanel.js file.

The following is the CSS code for the SpryTabbedPanel.css file. There are two main parts to this CSS: The first half is the styling for the horizontal tab layout. The second half is the styling for the vertical tab layout:

/* Horizontal Tabbed Panels */

.TabbedPanels {
	margin: 0px;
	padding: 0px;
	clear: both;
	width: 100%; /* IE Hack to force proper layout when preceded by a paragraph. (hasLayout Bug)*/
}

.TabbedPanelsTabGroup {
	margin: 0px;
	padding: 0px;
}

.TabbedPanelsTab {
	position: relative;
	top: 1px;
	float: left;
	padding: 4px 10px;
	margin: 0px 1px 0px 0px;
	font: bold 0.7em sans-serif;
	background-color: #DDD;
	list-style: none;
	border-left: solid 1px #CCC;
	border-bottom: solid 1px #999;
	border-top: solid 1px #999;
	border-right: solid 1px #999;
	-moz-user-select: none;
	-khtml-user-select: none;
	cursor: pointer;
}

.TabbedPanelsTabHover {
	background-color: #CCC;
}

.TabbedPanelsTabSelected {
	background-color: #EEE;
	border-bottom: 1px solid #EEE;
}

.TabbedPanelsTab a {
	color: black;
	text-decoration: none;
}

.TabbedPanelsContentGroup {
	clear: both;
	border-left: solid 1px #CCC;
	border-bottom: solid 1px #CCC;
	border-top: solid 1px #999;
	border-right: solid 1px #999;
	background-color: #EEE;
}

.TabbedPanelsContent {
	padding: 4px;
}
.TabbedPanelsContentVisible {
}

/* Vertical Tabbed Panels */

.VTabbedPanels .TabbedPanelsTabGroup {
	float: left;
	width: 10em;
	height: 20em;
	background-color: #EEE;
	position: relative;
	border-top: solid 1px #999;
	border-right: solid 1px #999;
	border-left: solid 1px #CCC;
	border-bottom: solid 1px #CCC;
}

.VTabbedPanels .TabbedPanelsTab {
	float: none;
	margin: 0px;
	border-top: none;
	border-left: none;
	border-right: none;
}

.VTabbedPanels .TabbedPanelsTabSelected {
	background-color: #EEE;
	border-bottom: solid 1px #999;
}

.VTabbedPanels .TabbedPanelsContentGroup {
	clear: none;
	float: left;
	padding: 0px;
	width: 30em;
	height: 20em;
}
      

Using the Tabbed Panel widget

This section contains the following topics:
  • To insert a Tabbed Panel widget
  • To add a panel to an Tabbed Panel widget
  • To style the Tabbed Panel widget

To insert a Tabbed Panel widget

  1. If not already done, locate the SpryTabbedPanel.js and add it to your web site. You can find the SpryTabbedPanel.js file in the /widgets/Tabbed Panel directory in the Spry zip.

For example, create a folder called “includes” in the root folder of your web site, and upload the SpryTabbedPanel.js file to it. The SpryTabbedPanel.js file contains all of the information necessary for making the Tabbed Panel widget interactive.

  1. If not already done, locate the SpryTabbedPanel.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.
  2. In the page code, link the SpryTabbedPanel.js file to your web page by inserting the following script tag in the page’s head tag:
<script src="includes/SpryTabbed Panel.js"></script>

Make sure the file path to the SpryTabbed Panel.js file is correct. This path will vary depending on where you include the file in your web site.

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

Make sure the file path to the SpryTabbedPanel.css file is correct. This path will vary depending on where you include the file in your web site.

  1. Add the Tabbed Panel to your page by inserting the following div tag where you want the Tabbed Panel to appear on the page:
<div id="tp1" class="TabbedPanel">
</div>
  1. Add panels to the Tabbed Panel by inserting <ul class="TabbedPanel"> tags in the <div id="tp1"...> tag, as follows:
<div id="tp1" class="TabbedPanel">
   <ul class="TabbedPanelsTabGroup">
   </ul>
</div>
  1. Add as many <li>s as you will need for panels. In this example, we will make 4 tabs :
<div id="tp1" class="TabbedPanel">
   <ul class="TabbedPanelsTabGroup">
       <li class="TabbedPanelsTab">Tab 1</li>
<li class="TabbedPanelsTab">Tab 2</li>
<li class="TabbedPanelsTab">Tab 3</li>
<li class="TabbedPanelsTab">Tab 4</li> </ul>
</div>
  1. Below the <UL>, add a container <DIV> for the content panels:
<div id="tp1" class="TabbedPanel">
   <ul class="TabbedPanelsTabGroup">
       <li class="TabbedPanelsTab">Tab 1</li>
<li class="TabbedPanelsTab">Tab 2</li>
<li class="TabbedPanelsTab">Tab 3</li>
<li class="TabbedPanelsTab">Tab 4</li> </ul> <div class="TabbedPanelsContentGroup"> </div>
</div>
  1. Add the content <DIV>s in the content container:
<div id="tp1" class="TabbedPanel">
   <ul class="TabbedPanelsTabGroup">
       <li class="TabbedPanelsTab">Tab 1</li>
<li class="TabbedPanelsTab">Tab 2</li>
<li class="TabbedPanelsTab">Tab 3</li>
<li class="TabbedPanelsTab">Tab 4</li> </ul> <div class="TabbedPanelsContentGroup"> <div class="TabbedPanelsContent">Tab 1 Content</div>
<div class="TabbedPanelsContent">Tab 2 Content</div>
<div class="TabbedPanelsContent">Tab 3 Content</div>
<div class="TabbedPanelsContent">Tab 4 Content</div> </div>
</div>
  1. Initialize the Spry Tabbed Panel object by inserting the following script block after the HTML for the Tabbed Panel widget:
<script>
   var tp1 = new Spry.Widget.TabbedPanel("tp1");
</script>

The JavaScript operator new initializes the Tabbed Panel widget object, and transforms the div content with the ID of tp1 from static HTML markup into an interactive Tabbed Panel object. The Spry.Widget.TabbedPanel method is a constructor in the Spry framework that creates Tabbed Panel objects. The information necessary to initialize the object is contained in the JavaScript library, SpryTabbedPanel.js, that you linked at the beginning of this procedure. It’s important that you make sure the ID of the div tag matches the ID parameter you specified in the Spry.Widgets.TabbedPanel method. It’s also important that you make sure the JavaScript call comes after the HTML markup for the widget.

  1. Save the page. The complete code looks as follows:
<head>
   <link href="includes/SpryTabbedPanel.css" rel="stylesheet" type="text/css" />
   <script src="includes/SpryTabbed Panel.js"></script>
</head>
<body>
<div class="TabbedPanels" id="tp1">
   <ul class="TabbedPanelsTabGroup">
       <li class="TabbedPanelsTab">Tab 1</li>
       <li class="TabbedPanelsTab">Tab 2</li>
       <li class="TabbedPanelsTab">Tab 3</li>
       <li class="TabbedPanelsTab">Tab 4</li>
  </ul>
<div class="TabbedPanelsContentGroup">
    <div class="TabbedPanelsContent">Tab 1 Content</div>
    <div class="TabbedPanelsContent">Tab 2 Content</div>
   <div class="TabbedPanelsContent">Tab 3 Content</div>
   <div class="TabbedPanelsContent">Tab 4 Content</div>
</div>
</div>
<script>
    var tp1 = new Spry.Widget.TabbedPanel("tp1");
</script>
</body>


To add a panel to a Tabbed Panel widget

  1. Insert a <div> tag inside the content container <div> tag for the Tabbed Panel. Then, add another <LI> to the panel tabs list. The number of list items and the number of content DIVs needs to be 1:1.

You can add as many panels as you like. Copy and pasting an existing panel is a quick way of adding new panel. Just be sure that the tag nesting is correct.

To remove a panel from an Tabbed Panel widget

  1. Delete the desired content <div> tag from the container <div> tag for the Tabbed Panel and then remove it's corresponding list item from the tab list.

Styling the Tabbed Panel widget

The Tabbed Panel widget comes with a CSS file (SpryTabbedPanel.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 SpryTabbedPanel.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 Tabbed Panel widget. Additionally, the SpryTabbedPanel.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, .TabbedPanel + .TabbedPanel or .TabbedPanel > .TabbedPanel) are not supported in Internet Explorer up to and including version 6.

To change the appearance of the Tabbed Panel widget

  1. Open the SpryTabbedPanel.css file. You can find the SpryTabbedPanel.css file in the /widgets/Tabbed Panel directory in the Spry zip.
  2. Locate the CSS rule for the part of the Tabbed Panel that you want to change. For example, if you wanted to change the background color of the Tabbed Panel’s tabs, you would edit the .TabbedPanelsTab rule in the SpryTabbedPanel.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 SpryTabbedPanel.css file and HTML markup with class names or your own. Doing so does not affect the functionality of the widget.

The SpryTabbedPanel.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 Tabbed Panel width is stored in the .TabbedPanel class. Content Panel height is set in the TabbedPanelsContent 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.

Horizontal or Vertical Tabs

You can switch between having the tabs horizontally across the top of the widget, or vertically, along the left edge.

By default, the tabs are horizontal.

To switch to vertical, change the class on the main widget container tag from .TabbedPanels to .VTabbedPanels, using the default CSS file provided.

Tabbed Panel Behaviors

The Tabbed Panel widget comes with predefined behaviors. These behaviors consist of changing CSS classes when a particular event occurs. For instance, when a user hovers over a panel tab, the TabbedPanelsTabHover class is applied. This is similar to 'a:hover' for links. These behaviors are always applied to the Tabbed 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 Tabbed Panel widget

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

  3. TabbedPanelsTabSelected This class is added to the tab element of the panel that is currently showing.
    TabbedPanelsContentVisible This class is added to the content element of the panel that is currently showing.
    TabbedPanelsTabHover This class is added to a panel's tab element whenever the mouse enters it. It is automatically removed when the mouse leaves the tab.
    TabbedPanelsTabFocused This class is added to the tab element that currently has keyboard focus.

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

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

<script> 
   var tp1 = new Spry.Widget.TabbedPanel("tp1", { tabHoverClass: "hover", panelVisibleClass: "open", tabSelectedClass: "selected", tabFocusedClass: "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 arrow keys and/or custom keys. This is critical for those that can't or choose not to use the mouse.

Enabling keyboard navigation on a Tabbed 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, simply give each tab element <li> tag a TabIndex value:

<ul class="TabbedPanelsTabGroup">
   <li class="TabbedPanelTab" tabindex="0">Tab</li>
   <li class="TabbedPanelTab" tabindex="0">Tab</li>

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.

Default Open Tab

There will be instances when you will want a certain tab to be open when the page loads. This can be accomplished by setting the defaultTab option in the constructor. Remember that Spry uses a zero based counting system, so 0 is the first, leftmost tab.

<script> 
   var tp1 = new Spry.Widget.TabbedPanel("tp1", { defaultTab: 2 });  
</script>

Note: The Tabbed Panel panels use a 0 based counting system, so setting the value to 2 will open the 3rd panel.

Opening Tabs

You can programatically open different panels from Javascript using the following functions. Remember that Spry uses a zero based counting system, so 0 is the first, leftmost tab. If the tab has an ID, you can also use ID to refer to panels.

<button onclick="tp1.showPanel(0)" >open first panel</button>
<button onclick="tp1.showPanel('tabID')">open panel</button> <script> var tp1 = new Spry.Widget.TabbedPanel("tp1"); </script>


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