easy_svg_rename_icon()

Funktion · Easy SVG · Status: Stabil

easy_svg_rename_icon() ändert den Namen, den ein Icon in der Bibliothek und in der Auswahl des Icon-Blocks zeigt. Der Slug bleibt, jedes Template, jeder Shortcode und jeder gespeicherte Block, der das Icon nutzt, läuft also weiter. Und das SVG bleibt heil, was ein einfaches wp_update_post() nicht garantiert.

Verwendung

easy_svg_rename_icon( int $id, string $label ): string

Wann du es brauchst

• Ein Add-on oder eine eigene Admin-Seite lässt Icons umbenennen.
• Ein Migrationsskript räumt Icon-Namen in großer Zahl auf (zum Beispiel arrow_left_24px zu Arrow left).
• Du übersetzt oder vereinheitlichst die Namen, die Redakteure in der Auswahl sehen.

Wann nicht:

• Um den Slug zu ändern. Der Slug ist die Adresse des Icons und wird absichtlich nie geändert: Themes und gespeicherte Icon-Blöcke tragen ihn. Brauchst du einen anderen Slug, füg das Icon unter dem neuen Namen neu hinzu und pass die Stellen an, die es nutzen.
• Um den Namen nur in der Auswahl des Editors auf einer Website zu ändern. Ändere dafür label in easy_svg_registrable_icons, der gespeicherte Titel bleibt dann.

Parameter

Rückgabewert

Beispiele

Einfach

$state = easy_svg_rename_icon( $icon_id, sanitize_text_field( $label ) );

Ein Formular verarbeiten

function myplugin_handle_icon_rename() {
	check_admin_referer( 'myplugin_rename_icon' );

	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( esc_html__( 'You are not allowed to rename icons.', 'myplugin' ) );
	}

	$id    = isset( $_POST['icon_id'] ) ? absint( $_POST['icon_id'] ) : 0;
	$label = isset( $_POST['label'] ) ? sanitize_text_field( wp_unslash( $_POST['label'] ) ) : '';

	$state = easy_svg_rename_icon( $id, $label );

	wp_safe_redirect( add_query_arg( 'myplugin_rename', $state, wp_get_referer() ) );
	exit;
}
add_action( 'admin_post_myplugin_rename_icon', 'myplugin_handle_icon_rename' );

Namen in großer Zahl aufräumen

foreach ( easy_svg_stored_icons() as $icon ) {
	$clean = ucfirst( trim( str_replace( array( '_', '-' ), ' ', preg_replace( '/_?\d+px$/', '', $icon['label'] ) ) ) );

	if ( '' !== $clean && $clean !== $icon['label'] ) {
		easy_svg_rename_icon( $icon['id'], sanitize_text_field( $clean ) );
	}
}

Jeder Aufruf verwirft den Icon-Cache. Lass das also einmal laufen (zum Beispiel per WP-CLI mit wp eval-file), nicht bei jeder Anfrage. easy_svg_stored_icons() ist ein interner Helfer und nicht Teil der zugesagten API, halte solche Skripte also einmalig.

Defensiv: die Vertragsversion prüfen

Die Funktion gibt es seit EASY_SVG_ICONS_API 2 (Easy SVG 5.4.0).

if ( defined( 'EASY_SVG_ICONS_API' ) && EASY_SVG_ICONS_API >= 2 && function_exists( 'easy_svg_rename_icon' ) ) {
	$state = easy_svg_rename_icon( $icon_id, $label );
}

So funktioniert es

Warum es die Funktion gibt statt eines einfachen wp_update_post():

• kses. wp_update_post() speichert die ganze Zeile neu, also läuft auch post_content wieder durch content_save_pre. Der kses-Filter von WordPress kennt kein SVG und leert das Icon für jeden Benutzer ohne unfiltered_html (zum Beispiel Administratoren in einer Multisite). Die Funktion schaltet kses genau für diesen einen Schreibvorgang ab, falls es an war, und in einem finally-Block wieder an.
• Cache. Die Icon-Liste liegt einen Tag lang im Transient easy_svg_icons. easy_svg_forget_icons() erhöht die Option easy_svg_icons_version und löscht den Transient, die nächste Anfrage zeigt also den neuen Namen im Icon-Block. Die Funktion wird direkt aufgerufen, weil der Hook save_post_esw_icon, der das auch täte, nur registriert ist, solange die Icon-Bibliothek eingeschaltet ist.
• Slug. Es wird nur post_title übergeben, post_name kann sich also nicht bewegen.

Stolperfallen

• Ein Titel ohne Buchstaben oder Ziffern. Das Umbenennen klappt, aber easy_svg_update_icon_markup() leitet aus dem Titel einen Namen ab und antwortet bei einem Titel wie !!! oder einem in nicht lateinischer Schrift mit refused. Behalte Titel, aus denen sanitize_title() einen gültigen Slug macht, wenn das Icon später eine neue Grafik bekommen soll.
• Labels nur aus Leerraum. ' ' wird gespeichert. Trimme vor dem Aufruf.
• Eingaben mit Slashes. Schick den Wert vor dem Bereinigen durch wp_unslash(). Die Funktion slasht ihn für wp_update_post() selbst, also nicht doppelt slashen.
• Hooks laufen. save_post, save_post_esw_icon und post_updated feuern wie bei jeder Aktualisierung.
• Templates zeigen den Titel nicht. easy_svg_icon() gibt die Zeichnung aus. Der Titel erscheint nur als Ersatz-aria-label, wenn du decorative false ohne Label übergibst.

Siehe auch

• easy_svg_update_icon_markup()
• easy_svg_stored_icons()
• easy_svg_forget_icons()
• easy-svg/v1/library/rename
• EASY_SVG_ICONS_API
• easy_svg_icon()