Configuration¶

The Extension works out of the box and configures all relevant parameters automatically.

Only the TypoScript needs to be inserted in order to obtain a display in the frontend:

TypoScript Configuration¶

To enable the icons to be output in the frontend, a few things need to be defined in the TypoScript:

RTE content (bodytext) is transferred to a DataProcessor
Allowed content is defined for the RTE to enable the output of SVG elements
Templates are added so that the icon field contained in the extension can be rendered for the title of a record.
A small CSS is added to the frontend output to achieve a consistent display of different icons.

All these values can of course be overwritten individually.

Tip

Take a closer look at the content of iconpack/Configuration/TypoScript/setup.typoscript to make individual adjustments.

If you want to keep the default settings, simply add the TypoScript provided at the end of your setup:

Note

If you use EXT:bootstrap_package_iconpack, make sure you include the templates at the end, otherwise lib.parseFunc_RTE will be overwritten by EXT:bootstrap_package and the icons cannot be displayed by the RTE.

Overriding Settings¶

The basic representation of icons is defined in the respective iconpack via the "renderTypes" key, and can be subsequently overwritten at any time using TypoScript for the frontend. The defined values are keywords separated by commas, which represent a sequence. If an iconpack does not contain the requested renderType, the next defined renderType is used.

To override the default settings for rendering iconpacks, the key plugin.tx_iconpack.overrides.renderTypes is created in the template or in the respective page. The settings can apply to all iconpacks with the key _default, or can refer to a specific iconpack.

The following examples show such a configuration for the frontend.

Override Settings in the Frontend¶

The settings for the frontend are made in the TypoScript Setup. Rendering in the frontend is done via dataProcessing, which can be assigned to any custom fields.

plugin.tx_iconpack {
   settings {
      # This classname will be the added in the frontend to all icons
      cssClass = iconpack
      # This can be used to override the rendering of the icons in the frontend.
      overrides {
         renderTypes {
            _default {
               native = svgSprite, webfont
               rte = webfont
            }
            fa5 {
               native = svgInline
            }
            glyphicons = webfont
         }
      }
   }
}

Extension Configuration¶

You can control whether the required assets should be included automatically and whether the CKEditor should be configured automatically.

Some iconpacks also offer the option of choosing between different icon set versions and other options. These settings are made in the extension configuration of the respective iconpack.

The following settings are currently available:

autoConfigRte¶

Type: bool
Default: 1

If enabled, the CKEditor will be configured automatically (no PageTS needed), so that the icons inserted in the RTE and their values are preserved when saving. If this option is disabled, these parameters must be inserted manually in the custom YAML configuration for the CKEditor.

autoAddAssets¶

Type: bool
Default: 1

If enabled, all CSS files required by the installed iconpacks are automatically included in the frontend.

Important

Changing the extension configuration requires an emptying of the TYPO3 cache for the changes to take effect!

If you deactivate these settings, however, you will have to make the required configuration yourself and integrate it into your own setup. Use the following two examples...

Example of manual CKEditor 4 configuration (TYPO3 v10/11)¶

editor:

   externalPlugins:
      iconpack: { resource: 'EXT:iconpack/Resources/Public/JavaScript/v11/CKEditor/plugin.js' }

   config:
      # Note: CSS files required by specific iconpacks is loaded automatically!
      contentsCss:
         - 'EXT:iconpack/Resources/Public/Css/Backend/CKEditor.min.css'

      # This configuration is necessary so that certain contents can be inserted in CKEditor4 in the first place.
      # All values defined here finally end up in the RTE and can be edited there.
      #
      # Note, however, that these values are additionally filtered again with PHP when saving, and ultimately only the attributes
      # defined here are actually stored in the database. In addition, for the output in the frontend on the one hand the
      # RteHtmlParser is used and on the other hand the Sanitizer, which finally decides which output ends up in the FE.
      #
      # More information about the RTE content filter can be found here:
      #   https://ckeditor.com/docs/ckeditor4/latest/examples/acfcustom.html
      #   https://ckeditor.com/docs/ckeditor4/latest/guide/dev_advanced_content_filter.html
      #
      extraAllowedContent:
         # webfont: Allow <span> tags
         - span(*)[!data-iconfig,id,name,class,style,alt,title]{color,background*,margin,padding,align,vertical-align}
         # image: Allow svg images
         - img[!data-iconfig,id,name,class,style,alt,title]{margin,padding,align,vertical-align}

      extraPlugins:
         - iconpack

Example of manual CKEditor 5 configuration (TYPO3 v12)¶

editor:
   config:
      # Note: CSS files required by specific iconpacks is loaded automatically!
      contentsCss:
         - 'EXT:iconpack/Resources/Public/Css/Backend/CKEditor.min.css'

      # Load modules for plugins when CKEditor is initialized
      # See CKEditor plugin API for details
      importModules:
         - { module: '@quellenform/iconpack-ckeditor.js', exports: [ 'Iconpack' ] }

      toolbar:
         items:
            - '|'
            - Iconpack

(Please take at look at the examples, located in Configuration/RTE/)