easy_svg_pro_registered_icon

Filter · Easy SVG Pro · Status: Stabil

WordPress 7.1 hat eine eigene Icon-Registry, und der Core-Icon-Block zeichnet, was dort liegt. Easy SVG Pro übergibt jedes Icon seiner Sammlungen an diese Registry. Dieser Filter sieht jedes Icon kurz vor der Übergabe, du kannst also das Markup ändern, das der Icon-Block zeigt, zum Beispiel eine Klasse ergänzen.

Verwendung

apply_filters( 'easy_svg_pro_registered_icon', string $content, string $reference )

Angewendet in includes/core/collections.php, in registered_icon_content(), während die Sammlungen auf init mit Priorität 11 bei Core registriert werden.

Wann du es brauchst

• Jedes Icon einer Sammlung soll im Icon-Block eine Klasse tragen, damit das CSS deines Themes Größe oder Farbe steuern kann.
• Du willst die Zeichnung eines Icons nur im Icon-Block tauschen, etwa gegen eine vereinfachte Version, die Cores Filterung übersteht.
• Du willst beim Debuggen loggen, was in der Registry ankommt, weil ein Icon im Block leer aussieht.

Nicht geeignet, wenn:

• Du ändern willst, was easy_svg_icon(), Twig oder der Shortcode ausgeben. Die lesen das Markup der Sammlung direkt und sehen diesen Filter nie. Nimm dafür den Filter easy_svg_icon_markup des kostenlosen Plugins.
• Das Icon zur Bibliothek des kostenlosen Plugins gehört (easy-svg/...). Diese Bibliothek läuft durch den Filter easy_svg_registrable_icons des kostenlosen Plugins.
• Redakteure Größen und Farben pflegen sollen. Stile & Theme-Farben unter Icons → Funktionen nutzt diesen Filter bereits dafür.

Parameter

Rückgabewert

Standardwert

Die Ausgabe von easy_svg_core_icon() für das Icon, oder das gespeicherte Markup, wenn das kostenlose Plugin diese Funktion nicht hat.

Beispiele

Eine Klasse für jedes Icon einer Sammlung

/**
 * "acme-icon" an das svg-Element jedes acme/*-Icons im Icon-Block hängen.
 * Ergänzt ein vorhandenes class-Attribut, statt ein zweites anzulegen.
 */
function acme_registered_icon_class( $content, $reference ) {
	if ( 0 !== strpos( $reference, 'acme/' ) ) {
		return $content;
	}

	if ( preg_match( '/<svg\b[^>]*\bclass="/i', $content ) ) {
		return (string) preg_replace( '/(<svg\b[^>]*\bclass=")/i', '$1acme-icon ', $content, 1 );
	}

	return (string) preg_replace( '/<svg\b/i', '<svg class="acme-icon"', $content, 1 );
}
add_filter( 'easy_svg_pro_registered_icon', 'acme_registered_icon_class', 20, 2 );

Priorität 20 läuft nach Stile & Theme-Farben, das sich auf 10 einhängt. Dessen Klassen sind also schon da, wenn du deine ergänzt.

Eine Klasse pro Kunde aus einer Zuordnung

/**
 * Agentur-Setup: Jede Kunden-Sammlung bekommt die Klasse, die ihr Theme erwartet.
 */
function acme_client_icon_classes( $content, $reference ) {
	$classes = array(
		'client-north' => 'north-icon',
		'client-south' => 'south-icon',
	);

	$collection = strtok( $reference, '/' );

	if ( ! isset( $classes[ $collection ] ) || false !== strpos( $content, $classes[ $collection ] ) ) {
		return $content;
	}

	return (string) preg_replace( '/<svg\b/i', '<svg class="' . esc_attr( $classes[ $collection ] ) . '"', $content, 1 );
}
add_filter( 'easy_svg_pro_registered_icon', 'acme_client_icon_classes', 20, 2 );

Diese Variante geht davon aus, dass das svg-Element noch keine Klasse hat. Nutzt du auch Stile & Theme-Farben oder Icons mit Strichen, nimm die ergänzende Variante oben.

Herausfinden, was im Icon-Block ankommt

/**
 * Nur zum Debuggen: den Registry-Inhalt eines Icons loggen. Nie ausliefern.
 */
function acme_debug_registered_icon( $content, $reference ) {
	if ( defined( 'WP_DEBUG_LOG' ) && WP_DEBUG_LOG && 'acme/phone' === $reference ) {
		error_log( 'Registry content for acme/phone: ' . $content );
	}

	return $content;
}
add_filter( 'easy_svg_pro_registered_icon', 'acme_debug_registered_icon', 99, 2 );

Steht im geloggten Markup ein circle, ein g oder ein stroke, verwirft Core das. Deshalb kann ein Icon im Block leer aussehen, obwohl es über easy_svg_icon() richtig erscheint.

So funktioniert es

Der Filter läuft nur, wenn all das zutrifft:

• Die Lizenz ist aktiv und Mehrere Sammlungen ist unter Icons → Funktionen eingeschaltet.
• WordPress kennt wp_register_icon() und wp_register_icon_collection(), also WordPress 7.1 oder neuer.

Dann bei jedem Request auf init mit Priorität 11, nach den Quellen (Priorität 9) und der kostenlosen Bibliothek (Priorität 10):

1. Jede Sammlung der Registry wird bei Core registriert: Ordnerquellen, das Theme, Code-Registrierungen und veröffentlichte Icon-Sets.
2. Für jedes Icon läuft das Markup durch easy_svg_core_icon() des kostenlosen Plugins, dann durch diesen Filter, dann an wp_register_icon(), mit dem Label aus dem Manifest oder dem Slug als Wörter.
3. Core lässt wp_kses mit seiner eigenen Allow-Liste über den Inhalt laufen und behält nur das.

Was Core behält (gemessen auf WordPress 7.1.3, einen Filter dafür gibt es nicht):

Alles andere, auch circle, rect, g, style und jedes stroke-Attribut, fällt weg. Deshalb schreibt das kostenlose Plugin Formen als Pfade um und macht aus Strichen Klassen, bevor dein Filter läuft.

Der Filter läuft einmal pro Icon und Request. Eine Seite mit 2000 Icons ruft ihn bei jedem Seitenaufruf 2000 Mal auf, halte deinen Callback also schlank.

Stolperfallen

• Core hat das letzte Wort. Alles außerhalb der Allow-Liste, das du ergänzt, entfernt Core lautlos. Ein style-Attribut, ein stroke oder ein data--Attribut kommt nie im Block an. Nimm Klassen und CSS.
• Nur der Icon-Block sieht es. easy_svg_icon(), Twig, der Shortcode und die Auswahlen lesen das Markup der Sammlung direkt. Änderst du hier eine Zeichnung, zeigen Block und Template unterschiedliche Icons.
• Nur ein class-Attribut. Das svg-Element kann schon Klassen aus der Strich-Umschreibung oder aus Stile & Theme-Farben tragen. Ein zweites class="" ergibt ungültiges Markup, und eins von beiden geht verloren. Ergänze das vorhandene Attribut.
• Nicht für die kostenlose Bibliothek. Icons mit der Adresse easy-svg/... kommen aus dem kostenlosen Plugin und laufen durch easy_svg_registrable_icons.
• Vor WordPress 7.1 passiert nichts. Ohne die Core-Icon-API läuft der Filter nie. Templates geben die Icons trotzdem über easy_svg_icon() aus.

Siehe auch

• easy_svg_pro_collection_icons
• easy_svg_register_icon_collection()
• Tutorial: Icons aus einem Theme oder Plugin ausliefern