easy_svg_icon()

Twig-Funktion · Easy SVG Pro · Status: Stabil

Timber-Themes schreiben ihr Markup in Twig, und dort gibt es keine PHP-Funktionen. Diese Twig-Funktion holt den Icon-Renderer des kostenlosen Plugins in deine Templates: Du nennst ein Icon über seine Adresse, und das Inline-SVG erscheint, schon bereinigt. Das klappt mit jeder Sammlung der Seite, von der kostenlosen Bibliothek bis zu Pro-Icon-Sets und Theme-Ordnern.

Verwendung

{{ easy_svg_icon( 'collection/slug' ) }}
{{ easy_svg_icon( 'collection/slug', { class: '', label: '', decorative: true } ) }}

Registriert in includes/twig/twig.php über den Filter timber/twig. Verfügbar seit Easy SVG Pro 1.7.0.

Wann du es brauchst

• Dein Theme ist mit Timber 1 oder Timber 2 gebaut und du willst Icons in .twig-Dateien.
• Du willst Inline-SVG, das currentColor erbt und per CSS gestaltet werden kann, kein img-Tag.
• Du brauchst dieselben Barrierefreiheits-Regeln wie easy_svg_icon() in PHP: standardmäßig dekorativ, mit Namen, sobald du ein Label übergibst.

Nicht dafür gedacht:

• Die Icon-Adresse kommt aus einem Feld und du magst lieber eine Pipe. Die Filter-Form macht dasselbe.
• Du willst nur wissen, ob ein Icon existiert. Nimm easy_svg_icon_exists().
• Dein Template ist reines PHP. Ruf dann easy_svg_icon() aus dem kostenlosen Plugin direkt auf.

Parameter

Rückgabewert

Standardwert

Ohne args ist das Icon dekorativ: aria-hidden="true" focusable="false" landen am svg-Element, eine Klasse gibt es nicht.

Beispiele

Ein dekoratives Icon neben Text

<a class="contact-link" href="tel:+4930123456">
	{{ easy_svg_icon( 'acme/phone', { class: 'contact-link__icon' } ) }}
	Ruf uns an
</a>

Der Text sagt, was der Link tut, deshalb bleibt das Icon für Screenreader unsichtbar.

Ein Icon, das allein eine Bedeutung trägt

<button class="menu-toggle" aria-expanded="false">
	{{ easy_svg_icon( 'acme/menu', { label: __( 'Open menu', 'acme' ) } ) }}
</button>

Timber stellt __() in Twig bereit, das Label wird also übersetzt. Das SVG bekommt role="img" und aria-label mit dem übersetzten Text.

Agentur: ein Partial für jedes Icon einer Komponenten-Bibliothek

{# templates/partials/icon.twig #}
{% set icon_classes = 'c-icon' ~ ( size is defined and size ? ' c-icon--' ~ size : '' ) %}
{{ easy_svg_icon( name, { class: icon_classes, label: label|default( '' ) } ) }}

{% include 'partials/icon.twig' with { name: 'acme/arrow-right', size: 'sm' } only %}
{% include 'partials/icon.twig' with { name: 'acme/warning', label: 'Warnung' } only %}

Jedes Icon-Markup im Theme läuft über eine Datei. Änderst du später Klassen oder die Sammlung, änderst du es dort.

Defensiv: ein Ersatz, wenn das Icon fehlt

{% set icon %}{{ easy_svg_icon( 'acme/' ~ service.slug ) }}{% endset %}
{% if icon|trim is not empty %}
	{{ icon }}
{% else %}
	{{ easy_svg_icon( 'acme/generic-service' ) }}
{% endif %}

Der set-Block fängt die Ausgabe als sicheres Markup ein, {{ icon }} gibt also das SVG aus. Das Icon wird nur einmal gerendert, nicht zweimal wie bei easy_svg_icon_exists() mit anschließendem easy_svg_icon().

So funktioniert es

1. Auf init prüft Easy SVG Pro die Lizenz und die Funktion Timber / Twig unter Icons → Funktionen. Nur wenn beides an ist, hängt es sich an timber/twig. Timber 1 und Timber 2 wenden diesen Filter beide an, wenn sie ihre Twig-Umgebung bauen.
2. Beim Bau der Umgebung wird die Funktion mit is_safe: ['html'] hinzugefügt. Hat die Umgebung kein addFunction() oder fehlt die Klasse \Twig\TwigFunction, wird nichts hinzugefügt.
3. Bei jedem Aufruf gehen Name und Hash an easy_svg_icon() des kostenlosen Plugins. Das zerlegt die Adresse, holt das Markup über den Filter easy_svg_icon_markup (dort liefert Pro seine Sets und Ordner-Sammlungen) und setzt die Barrierefreiheits-Attribute.
4. Zurück kommt das gespeicherte, bereinigte und gehärtete Markup. Ist Stile & Theme-Farben eingeschaltet, sind dessen Vorlagen und Farbzuordnungen schon angewendet.

Es gibt keinen zweiten Renderer: Twig, PHP-Templates, Shortcodes und der Icon-Block zeichnen dasselbe Markup.

Stolperfallen

• Funktion aus heißt kaputtes Template, nicht leeres Icon. Läuft die Lizenz aus oder schaltet jemand Timber / Twig ab, wird die Funktion gar nicht registriert, und Twig bricht beim Kompilieren mit "Unknown function" ab. "Gibt nichts aus" gilt nur, solange die Funktion registriert ist. Kannst du nicht sicher sein, dass die Funktion an bleibt, schau dir das defensive Muster im Tutorial zu Timber und Twig an.
• Zuweisen verliert die Sicher-Markierung. {% set icon = easy_svg_icon( 'acme/phone' ) %} speichert einen normalen String, und {{ icon }} zeigt dann den SVG-Quelltext als Text. Nimm die set-Block-Form aus dem letzten Beispiel oder {{ icon|raw }}.
• Nicht in Attributen. Die Ausgabe ist nur für HTML als sicher markiert. In einem Attribut oder einem script-Block escapt Twig sie, und ein SVG gehört dort ohnehin nicht hin.
• Reine Slugs meinen die kostenlose Bibliothek. easy_svg_icon( 'phone' ) sucht in easy-svg, nicht in deinem Set. Schreib für Pro-Sammlungen immer collection/slug.
• Set-Slugs können vom Post-Slug abweichen. Auf Seiten, die ältere Versionen liefen, heißt die Sammlung eines Sets vielleicht acme-x. Kopier die Adresse aus dem Tab Icon-Sets, der den registrierten Slug zeigt.
• Template-Caches halten alte Ausgaben. Cachest du gerenderte Templates (Timber::render() mit Ablaufzeit oder ein Seiten-Cache), erscheint ein geändertes Icon erst, wenn dieser Cache abläuft.

Siehe auch

• easy_svg_icon (Twig-Filter)
• easy_svg_icon_exists()
• Tutorial: Timber und Twig