:navigation-title: Custom Provider

..  include:: /Includes.rst.txt
..  _development-custom-provider:

===================================
Creating a custom Icon Set Provider
===================================

An icon set provider is responsible for providing icons and writing the
necessary stylesheet. The class must implement
:php:`\DanielHaring\IconHub\Imaging\IconSet\IconSetProviderInterface`,
but typically extends
:php:`\DanielHaring\IconHub\Imaging\IconSet\AbstractIconSetProvider`
instead.

If the abstract class is used, you must specify the icon provider, which
will later be responsible for rendering the icons. You can use existing
core classes or your own implementations for this purpose.

..  code-block:: php
    :caption: EXT:my_ext/Classes/Imaging/IconSet/CustomIconSetProvider.php

    declare(strict_types=1);
    namespace Vendor\MyExt\Imaging\IconSet;

    use DanielHaring\IconHub\Imaging\IconSet\AbstractIconSetProvider;
    use TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider;

    class CustomIconSetProvider extends AbstractIconSetProvider
    {
        protected function getProviderName(): string
        {
            return SvgIconProvider::class;
        }
    }

..  _development-custom-provider-icons:

Providing icons
===============

The actual icons are provided via the generator method
:php:`provideIcons()`. This method is expected to yield instances of
:php:`\DanielHaring\IconHub\Imaging\IconDefinition`.

If the recommended abstract class is used, icons can be created using
the helper method :php:`createIcon()`.

..  code-block:: php
    :caption: EXT:my_ext/Classes/Imaging/IconSet/CustomIconSetProvider.php

    declare(strict_types=1);
    namespace Vendor\MyExt\Imaging\IconSet;

    use DanielHaring\IconHub\Imaging\IconSet\AbstractIconSetProvider;

    class CustomIconSetProvider extends AbstractIconSetProvider
    {
        public function provideIcons(): \Generator
        {
            yield $this->createIcon('tx-myext-dummy', 'Dummy');
        }
    }

..  _development-custom-provider-styles:

Write the stylesheet
====================

The :php:`provideIcons()` method is also primarily used to generate the
stylesheet.

The required styles can be written using :php:`$this->styles->write()`.
This method can be used as often as needed to accumulate styles.

Although not strictly necessary, it is highly recommended to check in
advance whether stylesheet writing is enabled to avoid unnecessary
computing. :php:`$this->styles->isEnabled()` can be used for this
purpose.

..  code-block:: php
    :caption: EXT:my_ext/Classes/Imaging/IconSet/CustomIconSetProvider.php

    declare(strict_types=1);
    namespace Vendor\MyExt\Imaging\IconSet;

    use DanielHaring\IconHub\Imaging\IconSet\AbstractIconSetProvider;

    class CustomIconSetProvider extends AbstractIconSetProvider
    {
        public function provideIcons(): \Generator
        {
            if ($this->styles->isEnabled()) {
                $this->styles->write('/* Base styles to write. */');
                $this->styles->write('/* Icon specific styles to write. */');
            }
            yield $this->createIcon('tx-myext-dummy', 'Dummy');
        }
    }

..  _development-custom-provider-example:

Full example
============

This is what a simplified, typical icon set provider looks like:

..  code-block:: php
    :caption: EXT:my_ext/Classes/Imaging/IconSet/CustomIconSetProvider.php

    declare(strict_types=1);
    namespace Vendor\MyExt\Imaging\IconSet;

    use DanielHaring\IconHub\Imaging\IconSet\AbstractIconSetProvider;
    use TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider;

    class CustomIconSetProvider extends AbstractIconSetProvider
    {
        public function provideIcons(): \Generator
        {
            if ($this->styles->isEnabled()) {
                $this->styles->write('/* Base styles for the icon set. */');
            }

            foreach (['dummy', 'test'] as $iconName) {
                if ($this->styles->isEnabled()) {
                    $this->styles->write('/* Styles for icon "' . $iconName . '". */');
                }
                yield $this->createIcon('tx-myext-' . $iconName, $iconName, [
                    'source' => 'EXT:my_ext/Resources/Public/Icons/' . $iconName . '.svg'
                ]);
            }
        }

        protected function getProviderName(): string
        {
            return SvgIconProvider::class;
        }
    }