Timber und Twig

Timber-Themes rendern ihr Markup mit Twig, und Twig kann PHP-Funktionen nicht direkt aufrufen. Easy SVG Pro ergänzt Timbers Twig um drei Dinge: die Funktion easy_svg_icon(), einen gleichnamigen Filter und easy_svg_icon_exists(). Dieses Tutorial führt dich vom Einschalten bis zu einer Komponenten-Bibliothek, die auch dann weiterläuft, wenn jemand die Funktion abschaltet.

Was du brauchst

• Timber 1 (getestet mit 1.23.1) oder Timber 2, als Plugin oder per Composer in deinem Theme.
• Easy SVG Support (das kostenlose Plugin) und Easy SVG Pro mit aktiver Lizenz.
• Die Funktionen, die deine Sammlungen brauchen: Icon-Set-Editor für Icon-Sets, Theme- und Ordner-Quellen für Theme- und Drop-in-Ordner. Die kostenlose Icon-Bibliothek braucht keine davon.

{{ easy_svg_icon( 'acme/phone' ) }}

Die drei Helfer

{{ easy_svg_icon( 'acme/phone' ) }}
{{ post.meta( 'easy_svg_icon' )|easy_svg_icon }}
{% if easy_svg_icon_exists( 'acme/award' ) %}...{% endif %}

Alle drei rufen easy_svg_icon() aus dem kostenlosen Plugin auf. Twig, PHP-Templates, Shortcodes und der Icon-Block zeichnen dasselbe Markup.

Barrierefreiheit in einer Regel

Ein Icon ist dekorativ, bis du ihm ein Label gibst.

{# Dekorativ: Der Text daneben sagt alles. #}
<a href="/kontakt">{{ easy_svg_icon( 'acme/mail' ) }} Kontakt</a>

{# Bedeutungstragend: Das Icon ist der einzige Inhalt des Buttons. #}
<button>{{ easy_svg_icon( 'acme/search', { label: __( 'Search', 'acme' ) } ) }}</button>

Dekorative Icons bekommen aria-hidden="true" focusable="false". Icons mit Label bekommen role="img" und aria-label. Mit decorative: false bleibt ein Icon auch ohne eigenes Label bedeutungstragend. Es heißt dann wie sein gespeicherter Titel (kostenlose Bibliothek) oder wie sein Slug, als Wörter gelesen.

Icons aus Feldern

Redakteure wählen Icons meist in einem Feld aus, und das Template zeichnet, was sie gewählt haben. Jede Auswahl, die Easy SVG Pro einbindet, speichert die Adresse als collection/slug:

• Block-Theme-Unterstützung registriert das Post-Meta easy_svg_icon für jeden Post-Type.
• Der Tab der ACF-Icon-Auswahl liefert mit dem Standard-Rückgabeformat String von ACF collection/slug.
• Felder aus Meta Box, Lazy Blocks und WPBakery speichern dieselbe Adresse.

{% for service in services %}
	<article class="service">
		{{ service.meta( 'easy_svg_icon' )|easy_svg_icon( { class: 'service__icon' } ) }}
		<h3>{{ service.title }}</h3>
	</article>
{% endfor %}

Ein fehlendes oder leeres Feld gibt nichts aus. Für das Icon selbst brauchst du also kein if, nur wenn du Wrapper-Markup drumherum ausgibst.

Eine Komponente, die nur einmal rendert

Prüfen mit easy_svg_icon_exists() und dann Zeichnen mit easy_svg_icon() rendert das Icon zweimal. In einer Schleife mit fünfzig Karten summiert sich das. Fang die Ausgabe lieber ein:

{# templates/components/icon-badge.twig #}
{% set icon %}{{ easy_svg_icon( ref, { class: 'badge__icon', label: label|default( '' ) } ) }}{% endset %}
{% if icon|trim is not empty %}
	<span class="badge">{{ icon }}</span>
{% endif %}

Der set-Block hält das Markup als sicher markiert. Die Kurzform {% set icon = easy_svg_icon( ... ) %} tut das nicht: Gibst du sie aus, erscheint SVG-Quelltext als Text, außer du hängst |raw an.

Templates absichern, wenn die Funktion aus ist

Die Twig-Helfer gibt es nur, solange die Lizenz aktiv und Timber / Twig eingeschaltet ist. Fällt eins davon weg, werden sie nicht registriert, und Twig kann kein Template mehr kompilieren, das sie aufruft. Die Fehlermeldung lautet dann "Unknown function" oder "Unknown filter". Auf einer Kundenseite kann das nach einer abgelaufenen Lizenz eine weiße Seite bedeuten.

Kannst du nicht garantieren, dass die Funktion an bleibt, registrier einen eigenen Wrapper unter einem anderen Namen. Er ruft die öffentliche Funktion easy_svg_icon() des kostenlosen Plugins direkt auf und hängt nicht an der Twig-Funktion von Pro:

/**
 * {{ acme_icon( 'acme/phone', { label: 'Ruf uns an' } ) }} in jedem Template.
 * Funktioniert mit und ohne die Funktion Timber / Twig und gibt nichts aus,
 * wenn Easy SVG Support fehlt.
 */
function acme_render_icon( $ref, $args = array() ) {
	if ( ! function_exists( 'easy_svg_icon' ) || ! is_string( $ref ) || '' === trim( $ref ) ) {
		return '';
	}

	return (string) easy_svg_icon( $ref, is_array( $args ) ? $args : array() );
}

function acme_twig_icon_helpers( $twig ) {
	if ( ! is_object( $twig ) || ! method_exists( $twig, 'addFunction' ) || ! class_exists( '\Twig\TwigFunction' ) ) {
		return $twig;
	}

	$safe = array( 'is_safe' => array( 'html' ) );
	$twig->addFunction( new \Twig\TwigFunction( 'acme_icon', 'acme_render_icon', $safe ) );

	if ( method_exists( $twig, 'addFilter' ) && class_exists( '\Twig\TwigFilter' ) ) {
		$twig->addFilter( new \Twig\TwigFilter( 'acme_icon', 'acme_render_icon', $safe ) );
	}

	return $twig;
}
add_filter( 'timber/twig', 'acme_twig_icon_helpers' );

Zwei Regeln machen das sicher:

• Nimm einen eigenen Namen. Registrier keinen Ersatz namens easy_svg_icon. Twig lehnt eine zweite Funktion mit demselben Namen ab, ein Ersatz, der zuerst läuft, würde also die Registrierung von Easy SVG Pro verhindern.
• Absichern beim Reinkommen, nicht beim Rausgehen. easy_svg_icon() liefert gespeichertes Markup, das das kostenlose Plugin schon bereinigt und gehärtet hat, deshalb ist is_safe hier in Ordnung. Nimm denselben Wrapper nicht für Markup von anderswo.

Pro-Icon-Sets und Ordner-Sammlungen brauchen trotzdem ihre eigenen Funktionen (Icon-Set-Editor, Theme- und Ordner-Quellen). Sind die aus, gibt der Wrapper für ihre Adressen nichts aus, und die Seite bleibt stehen.

Caching und Performance

• Jeder Aufruf rendert aus dem gespeicherten Markup. Es gibt keinen zusätzlichen HTTP-Request, und nichts wird eingebunden.
• Ist Stile & Theme-Farben eingeschaltet, werden Vorlagen und Farbzuordnung im selben Aufruf angewendet.
• Cachest du gerendertes Twig mit Timber::render( $file, $context, $expires ) oder einem Seiten-Cache, erscheint ein geändertes Icon erst, wenn dieser Cache abläuft. Leer ihn über easy_svg_pro_set_icons_written, wenn sich ein Set ändert.

Fehlersuche

Siehe auch

• easy_svg_icon() (Twig-Funktion)
• easy_svg_icon (Twig-Filter)
• easy_svg_icon_exists()
• Icons aus einem Theme oder Plugin ausliefern