Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

Icon themes that live in your extension

This page is for developers and designers who want their own class icons or file type icons in the admin. Exponential draws these small icons from an icon theme, a folder of images. Before July 2026 the only place for a…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/features/6.0/icon-themes-in-extensions.md

On this page

Icon themes that live in your extension

This page is for developers and designers who want their own class icons or file type icons in the admin. Exponential draws these small icons from an icon theme, a folder of images. Before July 2026 the only place for a theme was share/icons/, so a custom icon meant copying files into the core or overriding a kernel class. Since 20 July 2026 (commit 3a40db1988) an extension can ship its own icon theme: the functions of the former bciconextensions and bciconextensions_share_icons extensions are part of the kernel.

Warning

.htaccess slows down every request. When .htaccess files are enabled (AllowOverride anything but None), let alone used, Apache looks for them and reads and evaluates them on every request, in every directory of the path, and page loading times go up drastically (measured). The only real fix is to switch the feature off for the virtual host: AllowOverride None in the HTTPS virtual host, and the rules in the virtual host's own configuration as mod_rewrite rules. That is far faster in production speed tests and well worth the time it takes to optimize a production configuration. Switch over right away: copy the rules of the example HTTPS virtual host into your virtual host (with the static cache, also staticcache_offload.conf), set AllowOverride None, run apachectl configtest, reload Apache and test the site. The same rules for other servers: nginx, LiteSpeed, Caddy, IIS, Velocity (built in); where virtual host rules go in a control panel: Plesk, cPanel, DirectAdmin, ISPConfig. On LiteSpeed or OpenLiteSpeed, the server's own page cache can also answer anonymous visitors and crawlers without PHP: Page caching with LiteSpeed and OpenLiteSpeed.

Upgrading? If you used those two extensions, remove them from ActiveExtensions[]. No kernel class override and no EZP_AUTOLOAD_ALLOW_KERNEL_OVERRIDE setup are needed any more.

Put a theme in an extension

  1. Create the folders. One folder per size, then per group:

    extension/mycompany_icons/
  icons/
    crystal-admin/              the theme name
      32x32/apps/job.png
      16x16_indexed/apps/job.png
      icon.ini                  sizes and the class to icon map of this theme
  settings/icon.ini.append.php

  2. Write the theme's own icons/crystal-admin/icon.ini:

    #?ini charset="utf-8"?
[IconSettings]
Sizes[]
Sizes[normal]=32x32
Sizes[small]=16x16_indexed

[ClassIcons]
Default=mimetypes/empty.png
ClassMap[job]=apps/job.png

  3. Name the extension and the theme in the extension's settings/icon.ini.append.php:

    <?php /* #?ini charset="utf-8"?

[ExtensionSettings]
IconExtensions[]=mycompany_icons

[IconSettings]
Theme=crystal-admin
StandardTheme=crystal
AdditionalThemeList[]=crystal-admin

*/ ?>

  4. Activate the extension (ActiveExtensions[]=mycompany_icons in settings/override/site.ini.append.php), then:

    php bin/php/ezpgenerateautoloads.php -e
php bin/php/ezcache.php --clear-all --allow-root-user

  5. Open a folder of job items in the admin: the list shows your apps/job.png.

Extensions listed in IconExtensions[] are searched before share/icons/, in the order listed.

How an icon is found

  1. The current theme (Theme), in the extension folders, then in Repository (default share/icons).
  2. Each theme in AdditionalThemeList[], in the same order of places.
  3. StandardTheme.
  4. The theme's or override's Default icon, so a missing file never produces a broken image tag.

Icons in extensions are plain static files: the web server serves them with no extra PHP work per image. The shipped rules (.htaccess_root, the web server examples, Velocity) serve extension/<name>/icons/ since 6.0.15; a server configuration of your own needs the one rule in Web server rules.

The crystal-admin theme now ships an icon for the content class identifier job.

Settings

FileBlockKeyDefaultScopeMeaning
settings/icon.iniIconSettingsRepositoryshare/iconsinstallationDefault icon repository, relative to the document root
settings/icon.iniIconSettingsThemecrystalinstallationTheme tried first
settings/icon.iniIconSettingsStandardThemecrystalinstallationLast fallback theme
settings/icon.iniIconSettingsAdditionalThemeList[]emptyinstallationThemes searched before StandardTheme
settings/icon.iniExtensionSettingsIconExtensions[]emptyinstallationExtensions whose icons/ folder is searched; order matters

The full guide, with the class and the upgrade notes, is Icon support.

Become an Exponential Partner

Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.

Partners: start here How to apply

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x