Using icons is a good way for differentiating types in eZ publish. For instance in listings were there might be mixed types using icons allows users to quickly figure out what each entry in the list reflects.

Icons are used by default in the administration interface to make it easier to tell one class from another, extending this to custom templates is possible.

Note: The icon system was added in eZ publish 3.4.

Icon repository

All icons are found in the share/icons directory, it contains all global icons which are not bound to a specific design.
If you are setting up a site with rewrite rules you must make sure that this directory is not rewritten to index.php.

Icon themes

The new icons system uses the icon structure from the KDE project, this means that you can install any icon package from KDE.
The subfolder crystal is the default icon theme for eZ publish and is bundled with eZ publish, it is a stripped down version of the original icon theme with only the icons that are currently used by eZ publish.

Installing a new them is simply to unpack the icon archive in the share/icons folder and change the current theme in icon.ini.

Theme structure

A theme starts out with one folder for each icon size, typical sizes are 12x12, 16x16, 24x24, 32x32 and 48x48.
Currently eZ publish uses the 16x16 and 32x32 sizes.

Under each size folder there will be a series of folders which represents the icon categories, typical categories are actions, apps, devices, filesystems and mimetypes.
Currently eZ publish uses the apps, filesystems and mimetypes folders.

Categories

• actions - Icons for typical actions in applications.
• apps - Application icons.
• devices - Icons for Unix/Linux devices.
• filesystems - Icons for the filesystem, mostly folder variations.
• mimetypes - Icons for MIME types.

Configuring theme

The INI file icon.ini controls all settings for icons, and the group IconSettings contains the global settings.
The rest of the INI file is used to map mimetypes, classes and groups into icon files.

IconSettings

• Repository - The path to the icon repository relative to eZ publish, the default is share/icons and should not be changed.
• Theme - The current theme, this matches the subfolder in the icon repository. If you install new themes this must be changed.
• Size - The default size for icons, this size refers to the size aliases defined in Sizes.
• Sizes - Maps size aliases to real sizes in a theme. Default aliases are small, normal and large.

More icons?

As explained the number of icons bundled with eZ publish covers only the classes and mimetypes in the standard installation.
Installing the full crystal theme (or any other) will give you access to more icons.

If you want to add more custom icons this is possible but changing themes will not work properly (unless the icons are copied).
It is generally recommended to try to reuse the icons which are found in a theme.

Template usage

The template system has currently three operators, they are class_icon, classgroup_icon and mimetype_icon.
All operators share the same syntax which is:

{input|icon_operator( size_alias, title )}

The size_alias refers to the sizes defined by the setting Sizes. If not supplied the default size is used.

The title is the title for the icon, this will be used in the title and alt attributes of the img tag.
If not supplied the input value is used, this means that it is generally a good idea to supply a title.

The input depends on the icon operator but is always a string.

The output of the operator will be an img XHTML tag with a structure looking like this:

img src="/share/icons/crystal/16x16/filesystems/folder.png"

width="16" height="16"

alt="Folder" title="Folder"

class_icon

This operator is used to add icons to classes or objects based on their class identifier. The identifier is the input parameter.

{$class_identifier|class_icon( small|normal|large, $class_name )}

Example with a content node:

{let class=$node.object.content_class}

{$class.identifier|class_icon( small, $class.name )}

{/let}

Example with a class identifier:

{'forum'|class_icon( small, 'Forum' )}

classgroup_icon

This operator is used to add icons to class groups based on their class group name. The name is the input parameter.

{$group_name|classgroup_icon( small|normal|large, $group_name )}

Example with a class group:

{'content'|classgroup_icon( small, 'Content' )}

mimetype_icon

This operator is used to add icons to files based on their mimetype. The mimetype is the input parameter.

{$mimetype|mimetype_icon( small|normal|large, $mimetype_name )}

Adding a small icon to a PDF document:

{'application/pdf'|classgroup_icon( small, 'PDF document' )}

Add a normal icon to a text file:

{'text/plain'|classgroup_icon( normal, 'Text file' )}

Adding a normal icon for a quicktime video file:

{'video/quicktime'|mimetype_icon( normal, 'QuickTime Video' )}

Configuring icon types

To change an icon for a class you need to edit configuration file icon.ini or icon.ini.append.
In this file you can configure how different types (classes, groups and mimetypes) are mapped to an icon file.
The path of the icon file is always relative from the size directory of the current theme.

Changing class icons

Find the block ClassIcons and edit the ClassMap setting, this maps from the class identifier to the icon file path.

For instance to replace the folder icon change the folder entry to:

ClassMap[folder]=filesystems/folder_image.png

You can also add your own classes using the same method, for instance:

ClassMap[country]=apps/package.png

The default icon for unknown classes can be modified by changing the Default setting.

Changing class group icons

Find the block ClassGroupIcons and edit the ClassGroupMap setting, this maps from the class group name to the icon file path.
The group name is always in lowercase.

For instance to replace the Content group change the entry to:

ClassGroupMap[content]=filesystems/folder_video.png

You can also add your own class groups using the same method, for instance:

ClassGroupMap[crm]=apps/kuser.png

The default icon for groups can be modified by changing the Default setting.

Changing mimetype icons

Find the block MimeIcons and edit the MimeMap setting, this maps from the mimetype to the icon file path.
The mimetype can be specified fully or with just the group, the system will try to find a complete mimetype before it tries the group.
e.g. text/plain or just text.

For instance to replace the video file icon change the video entry to:

MimeMap[video]=mimetypes/image.png

You can also add extra mimetypes using the same method, for instance:

MimeMap[text/xml]=mimetypes/html.png

The default icon for mimetypes can be modified by changing the Default setting.