This page details nitty-gritty details about how the icon.module should work at a code level. This is the third 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 - How using icons should work from the end-user experience
- Design (this page) - How to implement the icons module at a code level.
Theme Implementation
Info file
The info file of a theme states what icons this theme supports. Most themes will not actually need to support a large number of icons, because frequently modules will provide the CSS and icons themselves. However, if the theme overrides
CSS file
Position all your icons as background images where needed in your theme, using the default icon pack.
Module Implementation
Info file
icons[file_generic] = my-module-file-generic
icons[file_pdf] = my-module-file-pdf
icons[upload] = my-module-file-upload
icons[folder] = my-module-file-folderModule
When outputting markup, use the special class you've defined for your icon.
<?php
theme_my_module_directory($contents) {
foreach ($contents as $file) {
$file_type = in_array($file->extension, array('pdf', 'png', 'jpg')) ? $file->extension : 'generic';
$output .= '<div class="my-module-file-'. $file_type .'">'. $file->name .'</div>';
}
return $output;
}
?>CSS file
Then position a default icon in your module's CSS file.
.my-module-file-generic {
background: url(/misc/icons/file-generic.png) no-repeat left center;
padding-left: 16px;
}Icon Pack Implementation
The only thing necessary for an icon pack will be an info file, mapping the standard icon name to the file name. This makes it so that we can use icon packs from other sources (KDE, Lullacons, Oxygen, etc) without having to rename any of the original files. Info file format:
icons[16][file_generic] = file_16.png
icons[16][file_pdf] = pdf_16.png
icons[16][upload] = upload_16.png
icons[16][folder] = folder_16.png
icons[32][file_generic] = file_32.png
icons[32][file_pdf] = pdf_32.png
icons[32][upload] = upload_32.png
icons[32][folder] = folder_32.pngThe list is formatted with the size of the icon first, such as 16 or 32 pixels, then the generic name for the icon. Note: should we flip the array order so that it's icon name first then size?
Core Icon Module Implementation
The icon.module is responsible for actually swapping out icon packs. In the core implementation, it should provide a way to use a single icon pack across the site per theme. For the contrib version, we might make it so that individual icons can be mixed and matched from any installed icon set.
The icon.module needs to read in all the info files for all modules, and the active theme, collecting the defined class names for icons. If both a module and theme define the same unique icon name, the theme should take precedence.
The by reading in the active icon pack, the icon.module will generate a dynamic CSS file mapping all the active icons to the classes defined by modules and the active theme.
Icon module should provide the default markup for outputting an icon by supplying the default theme_icon() function.
Icon module should provide convenient variables to .tpl.php files though icon_preprocess() (I think that's the name of the hook). Creating $icon_[icon name] variables for every .tpl.php file.