This is a list of specifications for building a module to manage icons. This is the second part of 3 development documents that should serve as an outline for building a module to manage icons in Drupal. This page is a wiki.
Requirements - What is needed for icons in Drupal.
Specifications (this page) - How using icons should work from the end-user experience
Design - How to implement the icons module at a code level.
The end-user experience
- Install a desired icon pack that has an appealing look to match your theme.
- Visit the settings page for your theme at admin/build/themes/settings/your-theme (making this easier to get to would be a bonus).
- Choose the icons you want for your site.
- Core implementation: Select the icon pack you wish to use for this theme, previews of a select number of icons are shown from each icon pack, or a single png that previews the icons similar to the theme preview at admin/build/themes.
- Contrib implementation: A list of icons that your theme and modules support is displayed in a table. The list of icons is on the left side, with the list of icon packs across the top. You choose the icons you want from each icon pack.
Themer experience
- Create a normal Drupal theme. Creating an icon set to match your theme is optional, as you can use the default icons provided by core and contrib modules. Recommending or bundling an icon pack might not be a bad idea.
- Create a set of icons that match your theme, basing it off of a standard list of core icons plus common contributed module icons.
- In the info file for your theme, build a list of icons that your theme supports. This will determine the interface at admin/build/themes/settings/your-theme.
- The info file includes icon_name => css class pairs.
- Write your CSS file to use the default icons provided by Drupal core, positioning them with background-images on the classes that you specified in your theme's info file.
- As the markup for your theme changes, you can update the icon_name => CSS class pairs so that the icons continue to be mapped even if the markup of your theme changes.
- In places where CSS is not appropriate for placement of an icon, themers can use $icon_[icon name] to place any icon directly in markup.
Module developer
- Create a normal module.
- In the info file for your module, provide a list of new icons that your module will expose to Drupal. Just like a theme, the list will be a icon_name => css class pair.
- Create default icons for each of the new icons your module exposes.
- Position the icons for your module in your interface by including a CSS file that positions your icons using background-image.
- Because the module does the icon_name to CSS class mapping, the module developer is free to change the markup of their module at any time, updating the info file so icons will continue to map even as the module evolves.
- In places where CSS is not appropriate for placement of an icon, module developers can use theme('icon', $icon_name) to place any icon directly in markup.