window.EasySvgPanel.registerTab()

JavaScript · Easy SVG · Status: Stabil

registerTab() fügt dem Icons-Panel eine eigene Seite hinzu. Du gibst eine ID und eine Funktion mit, die liefert, was der Tab zeigt, und das Panel setzt den Tab in seine linke Seitenleiste, in den Bereich deiner Wahl. Registrierst du dieselbe ID noch einmal, ersetzt die neue Fassung die alte.

Verwendung

window.EasySvgPanel.registerTab( {
	id: 'myaddon-report', // Pflicht
	render: ( ctx ) => element, // Pflicht
	label: 'SVG report',
	area: 'inspect',
	order: 30,
	icon: 'audit',
} );

Wann du es brauchst

• Dein Add-on braucht eine ganze Seite im Icons-Panel: einen Bericht, ein Werkzeug, ein eigenes Einstellungsformular.
• Du willst diese Seite neben den Tabs von Easy SVG statt auf einer eigenen Admin-Seite, mit derselben Optik und demselben Menü.
• Zusammen mit easy_svg_panel_menu_tabs soll der Tab über das Menü Icons erreichbar sein und, wenn du willst, auch für Benutzer ohne manage_options.

Wann nicht:

• Um Icons aus deinem Add-on zu zeigen. Die Icon-Bibliothek kann sie über registerCollections() neben den Icons der Site auflisten.
• Auf Sites, auf denen Easy SVG Pro nicht lizenziert ist, denn dort wird der Tab nicht gezeichnet (siehe Hinweis oben).
• Um festzulegen, wer den Tab nutzen darf. Die Berechtigung wird in PHP angegeben, nicht hier.

Parameter

Rückgabewert

Standardwert

Beispiele

Ein einfacher Tab

Ohne Build-Schritt: wp.element ist das React, das WordPress mitbringt und das Panel nutzt. Reih diese Datei über easy_svg_panel_enqueue mit dem Panel-Handle, wp-element und wp-i18n als Abhängigkeiten ein.

( function () {
	const panel = window.EasySvgPanel;
	if ( ! panel ) {
		return;
	}

	const { createElement: el } = window.wp.element;
	const { __ } = window.wp.i18n;

	function HelloTab() {
		return el( 'p', null, __( 'Hello from my add-on.', 'myaddon' ) );
	}

	panel.registerTab( {
		id: 'myaddon-hello',
		label: __( 'Hello', 'myaddon' ),
		area: 'setup',
		order: 60,
		render: () => el( HelloTab ),
	} );
} )();

Ein Tab, der Daten von deiner REST-Route lädt

ctx bringt alles mit, was eine Anfrage braucht. Die Komponente bricht ihre Anfrage ab, wenn der Benutzer den Tab wechselt, weil das Panel Tabs aushängt, die nicht offen sind.

( function () {
	const panel = window.EasySvgPanel;
	if ( ! panel ) {
		return;
	}

	const { createElement: el, useEffect, useState } = window.wp.element;
	const { __ } = window.wp.i18n;

	function ReportTab( { ctx } ) {
		const [ rows, setRows ] = useState( null );
		const [ error, setError ] = useState( '' );

		useEffect( () => {
			const controller = new AbortController();

			fetch( ctx.restRoot + 'myaddon/v1/report', {
				credentials: 'same-origin',
				headers: { 'X-WP-Nonce': ctx.nonce },
				signal: controller.signal,
			} )
				.then( ( response ) =>
					response.ok ? response.json() : Promise.reject( new Error( response.statusText ) )
				)
				.then( ( data ) => setRows( Array.isArray( data ) ? data : [] ) )
				.catch( ( e ) => {
					if ( 'AbortError' !== e.name ) {
						setError( e.message );
					}
				} );

			return () => controller.abort();
		}, [ ctx.restRoot, ctx.nonce ] );

		if ( error ) {
			return el( 'p', { role: 'alert' }, error );
		}
		if ( null === rows ) {
			return el( 'p', null, __( 'Loading…', 'myaddon' ) );
		}
		return el(
			'ul',
			null,
			rows.map( ( row ) => el( 'li', { key: row.id }, row.title ) )
		);
	}

	panel.registerTab( {
		id: 'myaddon-report',
		label: __( 'SVG report', 'myaddon' ),
		area: 'inspect',
		order: 30,
		icon: 'audit',
		render: ( ctx ) => el( ReportTab, { ctx } ),
	} );
} )();

Defensiv: ältere Panels und ein eigenes Icon

area und ein eigenes icon brauchen Vertragsstufe 2. Auf Stufe 1 funktioniert der Tab trotzdem und landet unter Einrichtung.

( function () {
	const panel = window.EasySvgPanel;
	if ( ! panel || 'function' !== typeof panel.registerTab ) {
		return;
	}

	const { createElement: el } = window.wp.element;
	const level = Number( panel.api || 1 );

	const tab = {
		id: 'myaddon-report',
		label: 'SVG report',
		render: () => el( 'p', null, 'Report' ),
	};

	if ( 2 <= level ) {
		tab.area = 'inspect';
		tab.order = 30;
		// Ein Haken, gezeichnet auf dem 24 mal 24 Raster des Panels.
		tab.icon = el( 'path', { d: 'M5 12l4 4L19 7' } );
	}

	panel.registerTab( tab );
} )();

So funktioniert es

registerTab() selbst legt das Objekt nur in einer Map nach id ab und benachrichtigt das Panel. Alles andere passiert, wenn das Panel rendert (src/panel/App.jsx):

1. Sammeln. Das Panel beginnt mit seinen eigenen Tabs (library, settings), dem Pro-Katalog (sets, audit, configurator, licence) und dem Tab upsell. Registrierte Tabs mit jeder anderen ID kommen als zusätzliche Tabs dazu, aber nur, wenn EasySvgPanelData.proLicensed wahr ist. Ein registrierter Tab mit einer Katalog-ID ersetzt den gesperrten Platzhalter dieses Pro-Tabs, sobald die Lizenz gültig ist (den Tab licence jederzeit, damit man einen Schlüssel eingeben kann).
2. Normalisieren. Jeder zusätzliche Tab bekommt seinen Bereich (area, sonst das alte group, sonst setup), seine Reihenfolge (Number( order ), wenn endlich, sonst 50) und sein Label (label, sonst die ID).
3. Nach Berechtigung filtern. Ein Tab bleibt nur, wenn der Benutzer caps[ tabCaps[ id ] ] hat, mit manage_options als Rückfall für IDs ohne Eintrag in easy_svg_panel_menu_tabs.
4. Sortieren. Nach Bereich (icons, design, inspect, security, setup), dann nach Reihenfolge.
5. Rendern. Die Seitenleiste zeichnet pro Tab einen Knopf. Für den Inhalt ruft das Panel bei jedem eigenen Rendern render( ctx ) für jeden Tab auf, die Tabs-Komponente hängt aber nur den offenen Tab ein (lazyMount und unmountOnExit). Ein Tabwechsel hängt den vorherigen aus.
6. Den offenen Tab wählen. Der Wert ?tab= in der Adresszeile gewinnt; eine ID, die nicht in der Liste steht, öffnet den ersten Tab. Ein Klick auf einen Tab schreibt ?tab= mit history.replaceState() neu.

Stolperfallen

• Keine Pro-Lizenz, kein Tab. Siehe Hinweis oben. Trag deinen Menüeintrag nur ein, wenn der Tab auch gezeichnet wird, sonst öffnet der Eintrag den ersten Tab.
• Keine Hooks direkt in render. Das Panel ruft render( ctx ) für jeden Tab bei jedem Rendern als schlichte Funktion auf. Hooks dort gehörten zur Komponente des Panels und gehen kaputt, sobald sich die Zahl der Tabs ändert. Pack useState, useEffect und Anfragen in eine Komponente und gib ein Element davon zurück.
• Halte render billig und ohne Nebenwirkungen. Es läuft auch für geschlossene Tabs.
• Beim Tabwechsel geht Zustand verloren. Der Tab wird ausgehängt. Halte ungespeicherte Eingaben kurz, speichere sie, oder leg sie außerhalb der Komponente ab.
• Brich deine Anfragen im Cleanup ab. Sonst kommt eine langsame Antwort an, nachdem der Benutzer weg ist, und überschreibt womöglich neueren Zustand.
• Mit SCRIPT_DEBUG laufen Effekte doppelt. Das Panel rendert in Reacts StrictMode; mit dem Entwicklungs-Build von React wird jeder Effekt eingehängt, ausgehängt und wieder eingehängt.
• Nimm das React von WordPress. wp.element oder window.React. Eine in dein Script gebündelte React-Kopie macht Hooks kaputt.
• render darf keinen DOM-Knoten liefern. Willst du mit schlichtem DOM-Code zeichnen, gib ein Element mit ref-Callback zurück und füll den Knoten dort.
• Kollisionen. settings, library oder upsell zu registrieren wird ignoriert. sets, audit, configurator oder licence zu registrieren übernimmt einen Pro-Tab. Die letzte Registrierung einer ID gewinnt.
• ctx-Werte aus PHP sind nicht immer typisiert. maxMbCeiling kann ein String sein; die Booleans sind schon umgewandelt.

Siehe auch

• window.EasySvgPanel
• easy_svg_panel_menu_tabs
• easy_svg_panel_enqueue
• window.EasySvgPanel.registerCollections()
• window.EasySvgPanel.api
• EASY_SVG_PANEL_API
• Ein Add-on für das Icons-Panel bauen