Easy Symbols & Icons Documentation

To the plugin

Easy Symbols & Icons enables the centralised management and use of icon fonts in WordPress. The plugin provides a Gutenberg block as well as a shortcode and takes care of managing the loaded fonts and their icons.

Prerequisites

WordPress 6.0 or higher
PHP 8.0 or higher

Installation

The plugin is built from the Git repository and then installed in WordPress as a ZIP file.

Create plugin

git clone https://github.com/FARN-Design/easysymbolsicons
cd easysymbolsicons

chmod +x scripts/build.sh
./scripts/build.sh

After a successful build, the project can be zipped and then uploaded via the WordPress plugin management.

Settings

Easy Symbols & Icons provides its own settings page in the WordPress backend. This is accessed via the Settings Page plugins registered.

General

The area General contains general information and notes on the plugin. Further general settings can be managed there.

Font Select

About the area Font Select the icon fonts used on the website are managed.

Select icon fonts for use
upload custom TTF fonts
upload custom OTF fonts
remove unused fonts
Save changes

After managing the fonts, Easy Symbols & Icons generates a merged CSS file for the available icon fonts and embeds it on the website.

Icon fonts

The plugin is designed for using various icon fonts. The font files are managed centrally and then made available for rendering icons on the website.

Supported font formats

.ttf – TrueType Font
.otf – OpenType Font

The processing of the font files is carried out, amongst other things, via the integrated FontLib library.

Location

The managed icon resources are located in the WordPress upload directory in the folder eics-icons filed.

wp-content/uploads/eics-icons/

The plugin automatically determines the actual upload path and the corresponding URL via wp_upload_dir().

Gutenberg block

Easy Symbols & Icons presents the Gutenberg block eics-icon available.

Insert icon

Open the Gutenberg editor.
Add the block eics-icon added.
Select the desired icon from the available icon selection.
Save or publish the content.

The block is automatically registered via WordPress and is then available in the block editor.

Shortcode

In addition to the Gutenberg block, the plugin registers the shortcode eics-icon.

[eics-icon]

The shortcode enables the output of an icon even in places where a Gutenberg block cannot be used.

The specific parameters of the shortcode are determined by the implementation of eics_render_icon_shortcode defined.

Icon usage

Easy Symbols & Icons tracks which icons are actually used on the website. This allows icon usage to be evaluated centrally.

Collection runs automatically on various WordPress content.

Posts and pages

When saving a post, the icon usage of the respective content is updated.

Additionally, when deleting a post, the corresponding usage information is updated or removed.

Navigation

When updating a WordPress navigation menu, the plugin renders the menu and analyses the icons contained within it.

Widgets

Widgets are also examined for used icons during updates and rendering.

Templates and template parts

When saving wp_template and wp_template_part the icon usage for the respective content is also updated.

REST API

Easy Symbols & Icons provides its own REST API under the namespace easysymbolsicons/v1 Ready.

Loaded fonts

GET /wp-json/easysymbolsicons/v1/loaded-fonts

The endpoint returns the glyph mappings for all currently loaded fonts.

Property	Value
Method	GET
Namespace	easysymbolsicons/v1
Route	/loaded-fonts
Authentication	None

Icons used

GET /wp-json/easysymbolsicons/v1/used-icons

The endpoint supplies the currently recorded used icons.

Property	Value
Method	GET
Namespace	easysymbolsicons/v1
Route	/used-icons
Authentication	None

If the icon usage cannot be returned as a valid array, the endpoint responds with the error Invalid font data and the HTTP status 500.

Automatic initialisation

When initialising the IconHandler, the required directories are checked and created if necessary. In addition, the unified CSS file for the icon fonts is generated and included.

The central initialisation is handled via the IconHandler executed. This is used as a singleton, so that only one instance of the handler is created within a request.

Plugin activation

Activating the plugin will update the icon usage for all existing content. This will initially build up the usage inventory.

Plugin deactivation

No additional action is currently carried out when deactivating the plugin.

CSS and font integration

Easy Symbols & Icons generates a merged CSS file for the available icon fonts. This unified CSS file is then included for using the icons.

This means the individual font definitions do not need to be manually integrated into the theme.

Technical structure

The plugin is split into several components:

Component	Task
`Blocks`	Register the Gutenberg block and the icon shortcode.
`IconHandler`	Central management of icons, fonts, CSS and icon usage.
`Settings`	Management of plugin settings.
`Settings Page`	Provides the settings page in the WordPress backend.
`RestHandler`	Provides the REST API endpoints.
`IconHandlerFontsTrait`	Font management functions.
`IconHandlerUsageTrait`	Functions for tracking icon usage.
`IconHandlerUtilsTrait`	Helper functions for icon processing.
`IconHandlerCssTrait`	Generation and management of the icon CSS files.

Note

The correct usage always depends on whether the desired icon is present in an actively loaded font. If multiple fonts use the same name, it is advisable to use the full syntax with the font prefix.

With Easy Symbols & Icons you get a centralised, high-performance and clean solution for icon fonts in WordPress – featuring a Gutenberg workflow, shortcode support and efficient font management.

Licence

Easy Symbols & Icons is released under the GPLv3.

Credits

Developed by Farn – Digital Brand Design.