Icon Advanced

This page covers the backend icon browser, IDE auto-complete, creating your own icon sets, and configuration tips. For everyday usage see the Icon helper, and for the configuration reference see Icon Configuration.

Backend browser

The plugin provides a built-in icon browser interface accessible at:

/admin/templating/icons

Features:

• Browse all configured icon sets.
• View icon conflicts between sets.
• Test icon rendering.
• Copy icon names for use in templates.

Securing access

WARNING

The backend browser is not protected by default. Make sure to restrict access behind your application's authentication/authorization.

The plugin registers Admin routes when it is loaded. Its controller extends the application's AppController, so the host application's authentication and authorization callbacks apply. Protect these routes through that application policy. A route option such as _auth => true does not enforce access by itself.

The browser reads Configure::read('Icon'). If you configured sets only in AppView, move those settings into the application's Icon configuration; otherwise the browser returns “No icon set defined yet!”. The helper also reads these shared defaults.

IDE auto-complete

Get full auto-completion for icon names using the IdeHelper plugin.

1. Install IdeHelper

composer require --dev dereuromark/cakephp-ide-helper

Load the IdeHelper plugin and configure Icon.sets in application configuration before running the generator. AppView-only settings are unavailable to this command.

2. Configure the generator task

// In config/app.php
'IdeHelper' => [
    'generatorTasks' => [
        \Templating\Generator\Task\IconRenderTask::class,
    ],
],

3. Generate annotations

bin/cake ide_helper generate

4. IDE auto-complete

Your IDE will now provide auto-completion for the icon names:

$this->Icon->render('home'); // Complete an icon name inside the string

Creating custom icon sets

1. Create the icon class

<?php declare(strict_types=1);

namespace App\View\Icon;

use Templating\View\Icon\AbstractIcon;
use Templating\View\HtmlStringable;

class CustomIcon extends AbstractIcon {

    public function __construct(array $config = []) {
        $config += [
            'template' => '<i class="custom-{{name}}"{{attributes}}></i>',
        ];

        parent::__construct($config);
    }

    public function names(): array {
        // Return array of available icon names
        return ['icon1', 'icon2', 'icon3'];
    }

    public function render(string $icon, array $options = [], array $attributes = []): HtmlStringable {
        if (!empty($this->config['attributes'])) {
            $attributes += $this->config['attributes'];
        }

        $options['name'] = $icon;
        $options['attributes'] = $this->template->formatAttributes($attributes);

        return $this->format($options);
    }
}

2. Register the icon set

'Icon' => [
    'sets' => [
        'custom' => \App\View\Icon\CustomIcon::class,
    ],
],

3. Use the custom icons

echo $this->Icon->render('custom:icon1');

Tips and configuration tips

Icon mapping strategy

Create semantic aliases for better maintainability:

'Icon' => [
    'map' => [
        // Actions
        'create' => 'bs:plus-circle',
        'edit' => 'bs:pencil',
        'delete' => 'bs:trash',
        'save' => 'bs:check-circle',
        'cancel' => 'bs:x-circle',

        // Navigation
        'home' => 'bs:house',
        'back' => 'bs:arrow-left',
        'next' => 'bs:arrow-right',

        // Status
        'success' => 'bs:check-circle-fill',
        'warning' => 'bs:exclamation-triangle-fill',
        'error' => 'bs:x-circle-fill',
        'info' => 'bs:info-circle-fill',
    ],
],

Accessibility

Give an icon-only control an accessible name. Hide decorative icons beside visible labels using aria-hidden="true" and title => false. For an icon that needs its own label:

echo $this->Icon->render('delete', [], [
    'title' => __('Delete this item'),
    'aria-label' => __('Delete'),
]);

TIP

When using aliasing, the title is by default set to the same name. So aliasing helps to improve the out-of-the-box title building when you use speaking aliases.

CSS integration

For consistent styling across icon sets:

.icon {
    width: 1em;
    height: 1em;
    display: inline-block;
    vertical-align: middle;
}

.icon-sm { width: 0.875em; height: 0.875em; }
.icon-lg { width: 1.25em; height: 1.25em; }
.icon-xl { width: 1.5em; height: 1.5em; }

Animation support

For FontAwesome animations:

echo $this->Icon->render('fa6:spinner', [], [
    'class' => 'fa-spin',
    'title' => __('Loading...'),
]);

Responsive icons

echo $this->Icon->render('home', [], [
    'class' => 'd-none d-md-inline', // Hide on mobile
]);

---

Demo: sandbox.dereuromark.de/sandbox/templating-examples/icons

Repository: github.com/dereuromark/cakephp-templating