Easy Symbols & Icons Dokumentation

Zum Plugin

Easy Symbols & Icons ermöglicht die zentrale Verwaltung und Verwendung von Icon-Schriften in WordPress. Das Plugin stellt einen Gutenberg-Block sowie einen Shortcode zur Verfügung und übernimmt die Verwaltung der geladenen Schriftarten und ihrer Icons.

Voraussetzungen

WordPress 6.0 oder höher
PHP 8.0 oder höher

Installation

Das Plugin wird aus dem Git-Repository erstellt und anschließend als ZIP-Datei in WordPress installiert.

Plugin erstellen

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

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

Nach erfolgreichem Build kann das Projekt als ZIP-Datei gepackt und anschließend über die WordPress-Pluginverwaltung hochgeladen werden.

Einstellungen

Easy Symbols & Icons stellt eine eigene Einstellungsseite im WordPress-Backend bereit. Diese wird über die SettingsPage des Plugins registriert.

General

Der Bereich General enthält allgemeine Informationen und Hinweise zum Plugin. Weitere allgemeine Einstellungen können dort verwaltet werden.

Font Select

Über den Bereich Font Select werden die auf der Website verwendeten Icon-Schriften verwaltet.

Icon-Schriften zur Verwendung auswählen
eigene TTF-Schriften hochladen
eigene OTF-Schriften hochladen
nicht benötigte Schriften entfernen
Änderungen speichern

Nach der Verwaltung der Schriftarten erzeugt Easy Symbols & Icons eine zusammengeführte CSS-Datei für die verfügbaren Icon-Schriften und bindet diese auf der Website ein.

Icon-Schriften

Das Plugin ist für die Verwendung verschiedener Icon-Fonts ausgelegt. Die Schriftdateien werden zentral verwaltet und anschließend für die Icon-Ausgabe auf der Website bereitgestellt.

Unterstützte Font-Formate

.ttf – TrueType Font
.otf – OpenType Font

Die Verarbeitung der Schriftdateien erfolgt unter anderem über die eingebundene FontLib-Bibliothek.

Speicherort

Die verwalteten Icon-Ressourcen werden im WordPress-Upload-Verzeichnis im Ordner eics-icons abgelegt.

wp-content/uploads/eics-icons/

Das Plugin ermittelt den tatsächlichen Upload-Pfad und die zugehörige URL automatisch über wp_upload_dir().

Gutenberg-Block

Easy Symbols & Icons stellt den Gutenberg-Block eics-icon zur Verfügung.

Icon einfügen

Öffnen Sie den Gutenberg-Editor.
Fügen Sie den Block eics-icon hinzu.
Wählen Sie das gewünschte Icon aus der verfügbaren Icon-Auswahl.
Speichern bzw. veröffentlichen Sie den Inhalt.

Der Block wird automatisch über WordPress registriert und steht anschließend im Block-Editor zur Verfügung.

Shortcode

Zusätzlich zum Gutenberg-Block registriert das Plugin den Shortcode eics-icon.

[eics-icon]

Der Shortcode ermöglicht die Ausgabe eines Icons auch an Stellen, an denen kein Gutenberg-Block verwendet werden kann.

Die konkreten Parameter des Shortcodes werden durch die Implementierung von eics_render_icon_shortcode definiert.

Icon-Verwendung

Easy Symbols & Icons erfasst, welche Icons auf der Website tatsächlich verwendet werden. Dadurch kann die Verwendung von Icons zentral ausgewertet werden.

Die Erfassung wird automatisch bei verschiedenen WordPress-Inhalten ausgeführt.

Beiträge und Seiten

Beim Speichern eines Beitrags wird die Icon-Verwendung des jeweiligen Inhalts aktualisiert.

Zusätzlich werden beim Löschen eines Beitrags die zugehörigen Nutzungsinformationen aktualisiert bzw. entfernt.

Navigationen

Beim Aktualisieren eines WordPress-Navigationsmenüs rendert das Plugin das Menü und analysiert die darin enthaltenen Icons.

Widgets

Auch Widgets werden bei der Aktualisierung und beim Rendern auf verwendete Icons untersucht.

Templates und Template Parts

Beim Speichern von wp_template und wp_template_part wird ebenfalls die Icon-Verwendung des jeweiligen Inhalts aktualisiert.

REST API

Easy Symbols & Icons stellt eine eigene REST-API unter dem Namespace easysymbolsicons/v1 bereit.

Geladene Fonts

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

Der Endpoint liefert die Glyph-Zuordnungen aller aktuell geladenen Fonts.

Eigenschaft	Wert
Methode	GET
Namespace	easysymbolsicons/v1
Route	/loaded-fonts
Authentifizierung	Keine

Verwendete Icons

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

Der Endpoint liefert die aktuell erfassten verwendeten Icons.

Eigenschaft	Wert
Methode	GET
Namespace	easysymbolsicons/v1
Route	/used-icons
Authentifizierung	Keine

Kann die Icon-Verwendung nicht als gültiges Array zurückgegeben werden, antwortet der Endpoint mit dem Fehler Invalid font data und dem HTTP-Status 500.

Automatische Initialisierung

Beim Initialisieren des IconHandlers werden die benötigten Verzeichnisse geprüft und bei Bedarf angelegt. Außerdem wird die Unified-CSS-Datei für die Icon-Schriften erzeugt und eingebunden.

Die zentrale Initialisierung wird über den IconHandler durchgeführt. Dieser wird als Singleton verwendet, sodass innerhalb einer Anfrage nur eine Instanz des Handlers erzeugt wird.

Plugin-Aktivierung

Bei der Aktivierung des Plugins wird die Icon-Verwendung für alle vorhandenen Inhalte aktualisiert. Dadurch wird der Nutzungsbestand initial aufgebaut.

Plugin-Deaktivierung

Bei der Deaktivierung des Plugins wird aktuell keine zusätzliche Aktion ausgeführt.

CSS und Font-Einbindung

Easy Symbols & Icons erzeugt eine zusammengeführte CSS-Datei für die verfügbaren Icon-Schriften. Diese Unified-CSS-Datei wird anschließend für die Verwendung der Icons eingebunden.

Dadurch müssen die einzelnen Font-Definitionen nicht manuell in das Theme eingebunden werden.

Technischer Aufbau

Das Plugin ist in mehrere Komponenten aufgeteilt:

Komponente	Aufgabe
`Blocks`	Registriert den Gutenberg-Block und den Icon-Shortcode.
`IconHandler`	Zentrale Verwaltung der Icons, Fonts, CSS und Icon-Nutzung.
`Settings`	Verwaltung der Plugin-Einstellungen.
`SettingsPage`	Stellt die Einstellungsseite im WordPress-Backend bereit.
`RestHandler`	Stellt die REST-API-Endpunkte bereit.
`IconHandlerFontsTrait`	Funktionen zur Font-Verwaltung.
`IconHandlerUsageTrait`	Funktionen zur Erfassung der Icon-Verwendung.
`IconHandlerUtilsTrait`	Hilfsfunktionen für die Icon-Verarbeitung.
`IconHandlerCssTrait`	Erzeugung und Verwaltung der Icon-CSS-Dateien.

Hinweis

Die korrekte Verwendung hängt immer davon ab, ob das gewünschte Icon in einem aktiv geladenen Font vorhanden ist. Wenn mehrere Fonts denselben Namen verwenden, empfiehlt es sich, die vollständige Syntax mit Font-Präfix zu nutzen.

Mit Easy Symbols & Icons erhalten Sie eine zentrale, performante und saubere Lösung für Icon-Schriften in WordPress – mit Gutenberg-Workflow, Shortcode-Support und effizientem Font-Management.

Lizenz

Easy Symbols & Icons wird unter der GPLv3 veröffentlicht.

Credits

Entwickelt von Farn – Digital Brand Design.