:navigation-title: Site Settings

..  include:: /Includes.rst.txt
..  _configuration-site-settings:

=============
Site Settings
=============

Icons are defined on a per-page basis and are specified in the site
settings.

..  _configuration-icon-sets:

Configuration of icon sets
==========================

A single icon set uses a provider (e.g. *Icomoon*) to make multiple
icons available. These icons can then be used in both the backend and
frontend.

Multiple icon sets from different providers can be used per site.

..  code-block:: yaml
    :caption: config/sites/<my_site>/settings.yaml|typo3conf/sites/<my_site>/settings.yaml

    icons:
      sets:
        -
          provider: icomoon
          group: icomoon
          options:
            json: 'EXT:my_ext/Resources/Private/Fonts/Icomoon/selection.json'
            fonts: 'EXT:my_ext/Resources/Public/Fonts/Icomoon/'

The following settings are available for a single icon set.

..  confval:: provider
    :Path: icons.sets.<index>.provider
    :type: string

    The name of the provider to be used.

    Either a predefined abbreviation (e.g. “icomoon”) or the full class
    name.

    ..  code-block:: yaml
        :caption: config/sites/<my_site>/settings.yaml|typo3conf/sites/<my_site>/settings.yaml

        icons:
          sets:
            -
              provider: Vendor\MyExt\Imaging\IconSet\CustomIconSetProvider

..  confval:: group
    :Path: icons.sets.<index>.group
    :type: string

    Assigns the icon set to a group in the backend select fields.

    ..  code-block:: yaml
        :caption: config/sites/<my_site>/settings.yaml|typo3conf/sites/<my_site>/settings.yaml

        icons:
          sets:
            -
              provider: Vendor\MyExt\Imaging\IconSet\CustomIconSetProvider
              group: web_icons

..  confval:: options
    :Path: icons.sets.<index>.options
    :type: array

    Configures the respective icon set provider. (See
    :ref:`Icon provider options <configuration-icon-provider-options>`)

..  _configuration-icon-provider-options:

Icon provider options
=====================

Each icon set provider uses different options to make icons available.

The extension comes with a provider for integrating *Icomoon* icons, but
:ref:`can be expanded <development-custom-provider>` to include additional 
providers.

..  _configuration-provider-icomoon:

Icomoon
-------

..  confval:: json
    :Path: icons.sets.<index>.options.json
    :type: string

    The path to the `selection.json` file from *Icomoon*.

    Can be specified as either a storage path 
    (`1:/fonts/icomoon/selection.json`), an extension path 
    (`EXT:my_ext/Resources/Private/Fonts/Icomoon/selection.json`), or an 
    absolute path (`/fonts/icomoon/selection.json`).

    ..  code-block:: yaml
        :caption: config/sites/<my_site>/settings.yaml|typo3conf/sites/<my_site>/settings.yaml

        icons:
          sets:
            -
              provider: icomoon
              options:
                json: 'EXT:my_ext/Resources/Private/Fonts/Icomoon/selection.json'

..  confval:: fonts
    :Path: icons.sets.<index>.options.fonts
    :type: string

    The path to the font files.

    Can be specified as either a storage path
    (`1:/fonts/icomoon/`), an extension path
    (`EXT:my_ext/Resources/Public/Fonts/Icomoon/`), or an absolute path
    (`/fonts/icomoon/`).

    ..  code-block:: yaml
        :caption: config/sites/<my_site>/settings.yaml|typo3conf/sites/<my_site>/settings.yaml

          icons:
            sets:
              -
                provider: icomoon
                options:
                  fonts: '/fonts/icomoon/'