easy_svg_icon_markup

Filter · Easy SVG · Status: Stabil

Mit easy_svg_icon_markup änderst du das SVG eines Icons, kurz bevor easy_svg_icon() oder der Shortcode [easy_svg_icon] es ausgibt. Du kannst die eigenen Icons des Plugins anpassen oder für eine Sammlung antworten, die Easy SVG nicht kennt, sodass easy_svg_icon( 'acme/logo' ) das Icon deines Add-ons ausgibt.

Verwendung

add_filter( 'easy_svg_icon_markup', 'myplugin_icon_markup', 10, 3 );

function myplugin_icon_markup( string $markup, string $slug, string $collection ): string {
	return $markup;
}

Wann du es brauchst

• Du willst Icons auf dem Weg ins Template ein title-Element, width und height oder ein data-Attribut mitgeben.
• Du willst eine eigene Sammlung (ein Add-on, einen Theme-Ordner mit SVG-Dateien) über die eine Template-Funktion und den Shortcode ausliefern, die die Website schon nutzt.
• Du willst auf einer bestimmten Website ein Icon gegen ein anderes tauschen, ohne Templates anzufassen.

Wann nicht:

• Um zu ändern, was der Core-Block Icon oder wp_get_icon() zeichnet. Die lesen das Markup, das beim init an die Icon-Registry von WordPress übergeben wurde. Dafür gibt es easy_svg_registrable_icons.
• Um eine CSS-Klasse oder ARIA-Attribute zu setzen. Übergib class und label an easy_svg_icon(), die Funktion setzt sie nach diesem Filter.

Parameter

Rückgabewert

Standardwert

Das gespeicherte Markup für Icons aus easy-svg, ein leerer String für alles andere.

Beispiele

Einem Icon eine feste Größe geben

add_filter( 'easy_svg_icon_markup', 'mytheme_size_logo_icon', 10, 3 );

function mytheme_size_logo_icon( $markup, $slug, $collection ) {
	if ( 'easy-svg' !== $collection || 'logo' !== $slug || '' === $markup ) {
		return $markup;
	}

	return preg_replace( '/^(\s*<svg)\b/i', '$1 width="120" height="32"', $markup, 1 );
}

Fass nur Markup an, das du erkennst, und gib sonst immer das Original zurück.

Eine Sammlung aus deinem Theme ausliefern

Die Dateien liegen in wp-content/themes/mytheme/icons/*.svg. easy_svg_icon( 'mytheme/arrow' ) und [easy_svg_icon name="mytheme/arrow"] geben dann icons/arrow.svg aus, bereinigt wie die eigenen Icons des Plugins.

add_filter( 'easy_svg_icon_markup', 'mytheme_icon_collection', 10, 3 );

function mytheme_icon_collection( $markup, $slug, $collection ) {
	if ( 'mytheme' !== $collection || '' !== $markup ) {
		return $markup;
	}

	// Der Slug ist Benutzereingabe: nur Namen, die Easy SVG selbst akzeptieren würde.
	if ( ! defined( 'EASY_SVG_ICON_NAME_PATTERN' ) || 1 !== preg_match( EASY_SVG_ICON_NAME_PATTERN, $slug ) ) {
		return '';
	}

	$cache_key = 'mytheme_icon_' . $slug;
	$cached    = wp_cache_get( $cache_key, 'mytheme' );
	if ( false !== $cached ) {
		return $cached;
	}

	$file = get_theme_file_path( 'icons/' . $slug . '.svg' );
	if ( ! is_readable( $file ) ) {
		return '';
	}

	$sanitizer = function_exists( 'easy_svg_sanitizer' ) ? easy_svg_sanitizer() : null;
	if ( null === $sanitizer || ! function_exists( 'easy_svg_harden_icon_markup' ) ) {
		return '';
	}

	$clean = $sanitizer->sanitize( (string) file_get_contents( $file ) );
	$clean = is_string( $clean ) ? easy_svg_harden_icon_markup( $clean ) : '';

	wp_cache_set( $cache_key, $clean, 'mytheme', HOUR_IN_SECONDS );

	return $clean;
}

Einen Titel als Tooltip ergänzen

Ein title als Kindelement erscheint beim Überfahren mit der Maus als Tooltip. Nutz es zusätzlich zu label, nicht stattdessen.

add_filter( 'easy_svg_icon_markup', 'myplugin_icon_title', 10, 3 );

function myplugin_icon_title( $markup, $slug, $collection ) {
	if ( 'easy-svg' !== $collection || 'info' !== $slug || '' === $markup ) {
		return $markup;
	}

	$title = '<title>' . esc_html__( 'More information', 'myplugin' ) . '</title>';

	return preg_replace( '/(<svg\b[^>]*>)/i', '$1' . $title, $markup, 1 );
}

Defensiv: nur, wenn das Plugin den Filter hat

add_action( 'plugins_loaded', 'myplugin_hook_icons' );

function myplugin_hook_icons() {
	if ( ! function_exists( 'easy_svg_icon' ) ) {
		return; // Easy SVG ist nicht aktiv.
	}
	add_filter( 'easy_svg_icon_markup', 'myplugin_icon_title', 10, 3 );
}

So funktioniert es

Der Filter läuft in easy_svg_icon_markup(), das jeder Ausgabeweg aufruft:

• Er läuft einmal pro Aufruf von easy_svg_icon(), also einmal pro ausgegebenem Icon. Niemand speichert das gefilterte Ergebnis zwischen, teure Arbeit cachst du selbst, wie im Beispiel mit der Theme-Sammlung.
• Er läuft unabhängig davon, ob die Icon-Bibliothek eingeschaltet ist, und unter jeder WordPress-Version, denn die Template-Funktion braucht keine Icon-Registry des Cores.
• Der Core-Block Icon und wp_get_icon() rufen ihn nie auf.
• Easy SVG Pro liefert seine eigenen Sammlungen über genau diesen Filter durch easy_svg_icon() aus.

Stolperfallen

• Die Standard-Rückgabe vergessen. Ein Callback, der für Icons, die er nicht behandelt, nichts (oder null) zurückgibt, macht jedes Icon der Website zum leeren String. Gib auf jedem Weg $markup zurück.
• Anzahl der Argumente. Registriere mit 10, 3, sonst kommen $slug und $collection nie an.
• Hier class setzen. easy_svg_icon() fügt sein eigenes class-Attribut vor deinem ein, wenn der Aufrufer eins übergibt, und Browser behalten von zwei class-Attributen das erste. Lass die Aufrufer die Klasse übergeben.
• Ein leeres easy-svg-Icon füllen. Markup für einen fehlenden easy-svg-Slug wirkt in der Template-Funktion, aber nicht im Icon-Block. Redakteure und Theme sehen dann Unterschiedliches.
• Teure Callbacks. Eine Seite mit 40 Icons ruft dich 40-mal auf.

Siehe auch

• easy_svg_icon()
• [easy_svg_icon]
• easy_svg_icon_markup()
• easy_svg_registrable_icons
• easy_svg_sanitizer()
• easy_svg_harden_icon_markup()
• Icons in Themes ausgeben