Tapestry includes a collection of icons from the Tango Project Icon Library and from the FamFamFam Mini Library. If you enable the Use Icons checkbox on the theme configuration page, Tapestry will use these icons in various places throughout your site.

Tapestry can decorate menu items in the Primary Links menu with icons. The theme assigns a CSS class to each menu item in the Primary Links menu. If the assigned class name matches one of the menu classes defined in the icons.css file, the Tapestry will display the icon specified for that class.

Tapestry generates the CSS class name of a menu item based on the item's Title field. The title string is converetd to lowercase and filtered to eliminate spaces and special characters, and it is prepended with the string item-. A menu item with a Title of Home will be assigned a CSS class of item-home.

Let's take a look at a portion of CSS code from the file icons.css, which is located in the /tapestry/css folder.

/* primary links menu icons */
#primary li.item-home a {
	background: url(../icons/16x16/actions/gohome.png) left no-repeat;
}

#primary li.item-ideas a,
#primary li.item-products a,
#primary li.item-features a {
	background: url(../icons/16x16/status/info.png) left no-repeat;
}

#primary li.item-faq a,
#primary li.item-help a,
#primary li.item-handbook a {
	background: url(../icons/16x16/apps/help.png) left no-repeat;
}

Note that the first selector in the file defines a background image for the li.item-home a tag. This will match the class name generated by Tapestry for the menu item with a Title of Home, and therefore, the gohome.png icon is displayed.

Looking at the next selector group, we find that the info.png image will be used for Primary Link menu items with the name Ideas, Products, or Features. Because Tapestry processes the menu title, this image would also be used for the Titles ideas, IDEAS, or iDeAs.

Tapestry provides a handful of icons and CSS selectors for some common menu Titles. But there's no way we can anticipate every possible Title. If your Primary Links menu has an item that you want to decorate with an icon, you only need to add a new selector to the icons.css file and provide the icon.

Your new selector will need to specify the icon file name, and the class name will need to match the string generated by Tapestry for the menu item. It's pretty easy to determine the CSS class name for titles that are made up of a single word. Simply convert the Title string to lower case. For multi-word titles, you should omit spaces from the class name. If you're having trouble determining the generated class name, use your browser's View Source feature. Or better yet, use the Firebug plug-in for Firefox.

You can use PNG, JPG, or GIF files for your menu icons. Just be sure to get the filename correct in the CSS selector. You can place your icons anywhere within the Tapestry folder structure as long as the path in the CSS selector is correct. We recommend keeping them within the icons folder just to keep things tidy.

If the Alternate Icons for IE5/6 option on the theme settings page is enabled, older browsers will use the icons specified by the CSS file icons-ie6.css. This file is similar to the icons.css file, but the icon paths reference the alternate icons.

Tapestry only includes a small subset of the full Tango Project and FamFamFam Libraries. If you download the entire libraries from their sites, you will have thousands of icons to choose from. We've maintained the directory structure of the Tango library in Tapestry's icons folder to make adding new icons easy.