Zum Inhalt

InlineFontLoader — Lokaler Inline-Schriften-Loader

Extension for Magento 2

Bedienungsanleitung

CopeX GmbH
Web: https://copex.io
Email: office@copex.io

Inhaltsverzeichnis

Abschnitt Seite
1 Voraussetzungen 2
2 Installation 2
3 Konfiguration 2
4 Funktionsweise 5
5 Fehlerbehandlung 6

1 Voraussetzungen

  • Magento 2.4 oder höher
  • PHP 8.1 oder höher
  • Lokal gespeicherte Schriftdateien im Theme oder in einem Modul

2 Installation

Via Composer

composer require copex/module-inlinefontloader
php bin/magento module:enable CopeX_InlineFontLoader
php bin/magento setup:upgrade
php bin/magento cache:flush

3 Konfiguration

Die Konfiguration des Moduls finden Sie im Magento 2 Backend unter Shops > Konfiguration > Allgemein > Web > Lokaler Inline-Schriften-Loader.

Konfiguration

3.1 Aktivierung

  • Aktivieren — Aktiviert oder deaktiviert das Modul. Wenn deaktiviert, werden keine @font-face-Deklarationen oder Preload-Links in den HTML-Header eingefügt.

3.2 Schriftarten-Formate (Font Types)

  • Schriftarten-Formate — Eine Mehrfachauswahl, die bestimmt, welche Schriftdatei-Formate in die @font-face-CSS-Deklarationen eingebunden werden sollen. Nur die ausgewählten Formate werden im generierten CSS berücksichtigt.

Folgende Formate stehen zur Verfügung:

Format Dateierweiterung CSS-Format
WOFF2 .woff2 woff2
WOFF .woff woff
TrueType .ttf truetype
EOT (Internet Explorer) .eot embedded-opentype
SVG .svg svg

Empfehlung: Für moderne Browser reicht WOFF2 aus. Für maximale Kompatibilität können WOFF2 und WOFF kombiniert werden.

3.3 Preload-Formate (Preload Font Types)

  • Preload-Formate — Bestimmt, für welche Schriftdatei-Formate <link rel="preload"> Tags in den HTML-Header eingefügt werden sollen. Preloading beschleunigt das Laden der Schriften, da der Browser sie früher anfordert.

Hinweis: Für Preloading sollte in der Regel nur WOFF2 ausgewählt werden, da es das primäre Format für moderne Browser ist.

3.4 Schriftdefinitionen (Font-Konfiguration)

  • Konfigurieren — Eine Tabelle mit den zu ladenden Schriftdefinitionen.

Tabellenstruktur:

Spalte Beschreibung
Definition CSS-Eigenschaften der @font-face-Deklaration
Pfad zur Schriftart Pfad zur Schriftdatei ohne Dateierweiterung
Vorladen Ob für diese Schriftdefinition ein Preload-Link generiert werden soll

Definition (Beispiel):

font-family:'Roboto';font-style: normal;font-display: swap;font-weight: 400;

Pfad zur Schriftart (Beispiele):

  • Theme-relativer Pfad: fonts/roboto/roboto-v30-latin-regular
  • Modul-Pfad: CopeX_Core::fonts/myfont

Das Modul ergänzt automatisch die Dateierweiterungen basierend auf den konfigurierten Schriftarten-Formaten.

Vollständiges Konfigurationsbeispiel:

Definition Pfad zur Schriftart Vorladen
font-family:'Roboto';font-style:normal;font-display:swap;font-weight:400; fonts/roboto/roboto-v30-latin-regular Ja
font-family:'Roboto';font-style:italic;font-display:swap;font-weight:400; fonts/roboto/roboto-v30-latin-italic Nein
font-family:'Roboto';font-style:normal;font-display:swap;font-weight:700; fonts/roboto/roboto-v30-latin-700 Nein

4 Funktionsweise

4.1 Generierter HTML-Code

Das Modul fügt in den <head>-Bereich der Storefront-Seiten folgenden Code ein:

Preload-Links (für als "Vorladen" markierte Schriften): 

<link rel="preload" href="...fonts/roboto-v30-latin-regular.woff2" as="font" type="font/woff2" crossorigin>

Inline-CSS mit @font-face: 

<style>
@font-face {
  font-family: 'Roboto';
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: local('Roboto'),
       url('.../fonts/roboto-v30-latin-regular.woff2') format('woff2'),
       url('.../fonts/roboto-v30-latin-regular.woff') format('woff');
}
</style>

4.2 Fallback-Strategie

Ab Version 1.0.4 lädt das Modul bevorzugt remote Schriften und verwendet lokale Schriften nur als Fallback. Wenn ein Pfad zum Schriftdateinamen erkannt wird (z. B. Roboto), fügt das Modul automatisch local('Roboto') als erste Quelle in die src-Liste ein.

4.3 Caching

Die generierten @font-face-Deklarationen werden im Magento-Cache mit dem Tag config gespeichert. Nach Änderungen in der Konfiguration muss der Cache geleert werden, damit die neuen Einstellungen wirksam werden.

Cache leeren: 

php bin/magento cache:flush

4.4 Asset-Validierung

Das Modul überprüft beim Laden, ob die konfigurierten Schriftdateien tatsächlich existieren. Fehlende Dateien werden toleriert und führen nicht zu Fehlern — die entsprechenden src-Einträge werden einfach übersprungen.

5 Fehlerbehandlung

  • Schriften werden nicht geladen — Stellen Sie sicher, dass das Modul aktiviert ist und die Schriftdatei-Pfade korrekt konfiguriert sind. Überprüfen Sie im Browser-Entwicklertool (Netzwerk-Tab), ob die Schriftdateien korrekt angefordert werden.

  • @font-face wird nicht generiert — Leeren Sie den Magento-Cache nach Konfigurationsänderungen. Die generierten Deklarationen werden gecacht und werden nach einer Konfigurationsänderung nicht automatisch aktualisiert.

  • Schrift erscheint nicht im Browser — Überprüfen Sie, ob der Pfad zur Schriftdatei korrekt ist und die Datei im konfigurierten Format vorhanden ist. Theme-relative Pfade müssen unter web/ im Theme-Verzeichnis abgelegt sein.

  • 404-Fehler für Schriftdateien — Stellen Sie sicher, dass die statischen Dateien deployed wurden (php bin/magento setup:static-content:deploy). Überprüfen Sie, ob der angegebene Pfad relativ zum web/-Verzeichnis des Themes korrekt ist.

  • Preload-Links fehlen — Prüfen Sie, ob die gewünschten Formate unter Preload-Formate ausgewählt sind. Außerdem muss die jeweilige Schriftdefinition in der Konfigurationstabelle auf Vorladen: Ja gesetzt sein.

Lizenz

Proprietär — CopeX GmbH. Eine Lizenz pro produktiver Magento-Instanz.