Using Spry Widgets

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 Accordion widget are called SprySpryAccordion.css and SpryAccordion.js). The associated files for Spry widgets are located in widgets/accordion directory.

Anatomy of the Accordion widget

An Accordion widget is a set of collapsible panels that can store a great deal of content in a compact space. Users hide or reveal the content stored in the accordion by clicking the tab of the panel they want to access. The panels of the accordion expand or contract accordingly as the user clicks different tabs. In an accordion, only one content panel is open at a given time. The following illustration shows an Accordion widget, with the second panel expanded:

The HTML for the Accordion widget is comprised of an outer div tag that contains all of the panels, a div tag for each panel, and a header div and content div within the tag for each panel. An Accordion widget can contain as many individual panels as you like. The HTML for the Accordion widget also includes script tags in the head of the document and after the accordion’s HTML markup.

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

<head>
   ...
   <!--Link the CSS style  sheet that styles the accordion-->
   <link  href="SprySpryAccordion.css" rel="stylesheet"  type="text/css" />
   <!--Link the Spry Accordion  JavaScript library-->
   <script  src="includes/SpryAccordion.js"></script>
   </head>

<body> <!--Create the Accordion widget and assign classes to each element--> <div id="Acc1" class="Accordion"> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 1</div> <div class="AccordionPanelContent"> Panel 1 Content<br/> Panel 1 Content<br/> Panel 1 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 2</div> <div class="AccordionPanelContent"> Panel 2 Content<br/> Panel 2 Content<br/> Panel 2 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 3</div> <div class="AccordionPanelContent"> Panel 3 Content<br/> Panel 3 Content<br/> Panel 3 Content<br/> </div> </div> <div class="AccordionPanel"> <div class="AccordionPanelTab">Panel 4</div> <div class="AccordionPanelContent"> Panel 4 Content<br/> Panel 4 Content<br/> Panel 4 Content<br/> </div> </div> </div> <!--Initialize the Accordion widget object--> <script> var acc1 = new Spry.Widget.Accordion("Acc1"); </script></body>

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

You’l also notice that each of the div tags in the Accordion widget contains a CSS class. These classes control the style of the Accordion widget, and exist in the accompanying CSS file, SpryAccordion.css.
You can change the appearance of any given part of the Accordion 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 accordion’s tabs, you would edit the .AccordionPanelTab rule in the SpryAccordion.css file. In addition to the classes shown in the HTML markup, the Accordion 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, SpryAccordion.js. The accordion library includes behaviors related to hovering, tab clicking (to open panels), panel focus, and keyboard navigation.
You can change the look of the accordion as it relates to these behaviors by editing the appropriate classes in the SpryAccordion.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 SpryAccordion.js file.

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

Accordion Structure

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

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

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. Check the last example in the accordion sample page.

CSS for the Accordion widget

The accompanying file, SpryAccordion.css, contains the rules that style the Accordion widget. You can edit these rules to style the accordion’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 SpryAccordion.css file and HTML markup with class names or your own. Doing so does not affect the functionality of the widget. (CSS is not required for widget functionality).

The behaviors classes at the end of the style sheet are blank by default. Their default functionality is defined in the JavaScript library file SpryAccordion.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 SpryAccordion.js file.
Following is the CSS code for the SpryAccordion.css file:

  /*Accordion styling classes*/

.Accordion { font-family: Arial, Helvetica, sans-serif; font-size: 12px; width: 400px; float: left; margin: 4px;
border-left: solid 1px gray;
border-right: solid 1px black border-bottom: solid 1px gray;
overflow: hidden;
}

.AccordionPanel {
}

.AccordionPanelLabel { background-color: #CC0066; border-top: solid 1px black; border-bottom: solid 1px gray; padding: 2px; cursor: pointer; -moz-user-select: none;
-khtml-user-select: none;
}
.AccordionPanelContent {
overflow: auto;
// padding: 2px;
height: 200px;
}
:focus .AccordionPanelOpen .AccordionPanelTab {
background-color: yellow;
}

/*Accordion behaviors classes*/

.AccordionPanelLabelHover{ }
.AccordionPanelOpen{ }
.AccordionPanelClosed{ }
.AccordionPanelFocused{
}

Using the Accordion widget

This section contains the following topics:

To insert an Accordion widget

  1. If not already done, locate the SpryAccorion.js and add it to your web site. You can find the SpryAccordion.js file in the widgets/accordion directory.

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

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

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

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

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

  1. Add the accordion to your page by inserting the following div tag where you want the accordion to appear on the page:
   <div id="Acc1" class="Accordion">
   </div>
  1. Add panels to the accordion by inserting <div class="AccordionPanel"> tags in the <div id="Acc1"...> tag, as follows:
  <div id="Acc1" class="Accordion">
   <div  class="AccordionPanel">
   </div>
   <div  class="AccordionPanel">
   </div>
   </div>

The above code adds two panels to the accordion. You can add as many panels as you like.

  1. Add tabs to the panels by inserting <div class="AccordionPanelTab"> tags in each <div class="AccordionPanel"> tag, as follows :
<div  class="accordionPanel">
   <div  class="AccordionPanelTab">Panel 1 Title</div>
   </div>
  1. Add content to the panels by inserting <div class="AccordionPanelContent"> tags in each <div class="AccordionPanel"> tag, as follows:
  <div  class="AccordionPanel">
   <div class="AccordionPanelTab">Panel  1 Title</div>
     <div  class="AccordionPanelContent">
       Panel 1 Content
     </div>
   </div>

Insert the content between the opening and closing AccordionPanelContent tags. The content can be any valid HTML, including HTML form elements.

  1. Initialize the Spry accordion object by inserting the following script block after the HTML for the Accordion widget:
<script>
   var acc1 = new  Spry.Widget.Accordion("Acc1");
</script>

The JavaScript operator new initializes the Accordion widget object, and transforms the div content with the ID of Acc1 from static HTML markup into an interactive accordion object. The Spry.Widget.Accordion method is a constructor in the Spry framework that creates accordion objects. The information necessary to initialize the object is contained in the JavaScript library, SpryAccordion.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.Accordion 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="SpryAccordion.css" rel="stylesheet"  type="text/css" />
   <script  src="includes/SpryAccordion.js"></script>
   </head>
   <body>
   <div id="Acc1"  class="Accordion">
   <div class="AccordionPanel">
   <div class="AccordionPanelTab">Panel  1</div>
   <div class="AccordionPanelContent">
   Panel 1 Content<br/>
   Panel 1 Content<br/>
   Panel 1 Content<br/>
   </div>
   </div>
   <div class="AccordionPanel">
   <div class="AccordionPanelTab">Panel  2</div>
   <div class="AccordionPanelContent">
   Panel 2 Content<br/>
   Panel 2 Content<br/>
   Panel 2 Content<br/>
   </div>
   </div>
   <div class="AccordionPanel">
   <div class="AccordionPanelTab">Panel  3</div>
   <div class="AccordionPanelContent">
   Panel 3 Content<br/>
   Panel 3 Content<br/>
   Panel 3 Content<br/>
   </div>
   </div>
   <div class="AccordionPanel">
   <div class="AccordionPanelTab">Panel  4</div>
   <div class="AccordionPanelContent">
   Panel 4 Content<br/>
   Panel 4 Content<br/>
   Panel 4 Content<br/>
   </div>
   </div>
   </div>
<script>
   var acc1 = new Spry.Widget.Accordion("Acc1");
   </script>
</body>

To add a panel to an Accordion widget

  1. Insert a <div class="AccordionPanel"> tag inside the container <div> tag for the accordion. Be sure not to forget to add the closing </div> tag when you add the code. For example:
<div  class="AccordionPanel">
      <div class="AccordionPanelTab"></div>
         <div class="AccordionPanelContent"></div>
     </div>
</div>

The above code adds a panel to the accordion widget. 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 order is correct.

To remove a panel from an Accordion widget

  1. Delete the desired <div class="AccordionPanel"> tag from the container <div> tag for the accordion. Be sure not to forget to delete the closing </div> tag when you delete the code.

For more information, see “To insert an Accordion widget” on page 38.

To style the Accordion widget

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

To change the appearance of the Accordion widget

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

The SpryAccordion.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 accordion width is stored in the .Accordion class. Content Panel height is set in the AccordionPanelContent 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.

Accordion Behaviors

The accordion widget comes with a few 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 AccordionPanelTabHover class is applied. This is similar to 'a:hover' for links. These behaviors are always applied to the accordion. 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.

Note: All the code samples below come from the Accordion sample file.

To change the behaviors of the Accordion widget

  1. Open the SpryAccordion.css file. You can find the SpryAccordion.css file in the widgets/accordion directory.
  2. Locate the CSS rule for the accordion behavior that you want to change. The Accordion widget comes with four built-in rules for behaviors:
  3. .AccordionPanelTabHover (Activates when hovering over the panel tab.)
    .AccordionPanelOpen     (Activates on the tab of the open panel.) 
    .AccordionPanelClosed   (Activates on the closed panels.)
    .AccordionFocused       (Activates when the whole accordion gets focus. See the first sample for an example.)
    
  4. Add CSS rules for any of the behaviors you wish to enable.

You cannot replace behavior-related class names in the SpryAccordion.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 accordion constructor:

<script> 
var acc2 = new Spry.Widget.Accordion("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 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 an accordion 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 accordion, simply give it a TabIndex value to the accordion container tag:

<div id="Acc1" class="Accordion" tabindex="0">

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.

Custom keys can be set for keyboard navigation. These are set as arguments of the accordion constructor script:

<script>  
var acc3 = new Spry.Widget.Accordion("Acc3", { nextPanelKeyCode: 78 /* n key */, previousPanelKeyCode: 80 /* p key */ });  
</script>

A keyboard mapping list can be found here.

Panel Animation

By default, the panels use animation to smoothly open and close. This animation can be turned off by sending an argument in the accordion constructor:

<script>  
var acc5 = new Spry.Widget.Accordion("Acc5", { enableAnimation: false });  
</script>

This will cause the panels to snap open and closed instantly.

Default Open Panel

There will be instances when you will want a certain panel to be open when the page loads. This can be accomplished by setting the defaultPanel option in the constructor.

<script> 
var acc8 = new Spry.Widget.Accordion("Acc8", { defaultPanel: 2 });  
</script>

Note that accordion panels use a 0 based counting system, so setting the value to 2 will open the 3rd panel.