window.EasySvgPanel.registerTab()

JavaScript · Easy SVG · Status: Stable

registerTab() adds a screen of your own to the Icons panel. You give it an id and a function that returns what the tab shows, and the panel puts the tab into its left rail, in the area you choose. Register the same id again and your new version replaces the old one.

Usage

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

When to use it

• Your add-on needs a full screen inside the Icons panel: a report, a tool, a settings form of its own.
• You want that screen next to Easy SVG's own tabs instead of a separate admin page, with the same look and the same menu.
• Combined with easy_svg_panel_menu_tabs, you want the tab reachable from the Icons menu and, if you like, by users without manage_options.

When not to use it:

• To show icons from your add-on. The Icon library tab can list them beside the site's own icons through registerCollections().
• On sites where Easy SVG Pro is not licensed, because the tab will not be drawn there (see the callout above).
• To decide who may use the tab. The capability is declared in PHP, not here.

Parameters

Return value

Default

Examples

A basic tab

No build step: wp.element is the React that WordPress ships and the panel uses. Enqueue this file through easy_svg_panel_enqueue with the panel handle, wp-element and wp-i18n as dependencies.

( 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 ),
	} );
} )();

A tab that loads data from your REST route

ctx carries everything a request needs. The component aborts its request when the user switches tabs, because the panel unmounts tabs that are not open.

( 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 } ),
	} );
} )();

Defensive: older panels and your own icon

area and a custom icon need contract level 2. On level 1 the tab still works and lands in Setup.

( 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;
		// A check mark, drawn on the panel's 24 by 24 grid.
		tab.icon = el( 'path', { d: 'M5 12l4 4L19 7' } );
	}

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

How it works

registerTab() itself only stores the object in a map keyed by id and notifies the panel. Everything else happens when the panel renders (src/panel/App.jsx):

1. Collecting. The panel starts with its own tabs (library, settings), the Pro catalogue (sets, audit, configurator, licence) and the upsell tab. Registered tabs with any other id are added as extra tabs, but only when EasySvgPanelData.proLicensed is true. A registered tab with a catalogue id replaces the locked placeholder of that Pro tab, once the licence is valid (the licence tab at any time, so a key can be entered).
2. Normalising. Each extra tab gets its area (area, else the legacy group, else setup), its order (Number( order ) when finite, else 50) and its label (label, else the id).
3. Filtering by capability. A tab stays only when the user holds caps[ tabCaps[ id ] ], falling back to manage_options for ids that have no entry in easy_svg_panel_menu_tabs.
4. Sorting. By area (icons, design, inspect, security, setup), then by order.
5. Rendering. The rail draws a button per tab. For the content, the panel calls every tab's render( ctx ) on each render of the panel, but the tabs component mounts only the open tab (lazyMount and unmountOnExit). Switching tabs unmounts the previous one.
6. Choosing the open tab. The ?tab= value in the address bar wins; an id that is not in the list opens the first tab. Clicking a tab rewrites ?tab= with history.replaceState().

Pitfalls

• No Pro licence, no tab. See the callout at the top. Only add your menu entry when the tab will be drawn, otherwise the entry opens the first tab.
• No hooks directly in render. The panel calls render( ctx ) for every tab on every render, as a plain function, so hooks called there would belong to the panel's own component and break as soon as the number of tabs changes. Put useState, useEffect and requests inside a component and return an element of it.
• Keep render cheap and free of side effects. It runs even for tabs that are closed.
• State is lost when the user switches tabs. The tab unmounts. Keep unsaved input short, save it, or store it outside the component.
• Abort your requests in the cleanup. Otherwise a slow answer arrives after the user left and can overwrite newer state.
• Effects run twice with SCRIPT_DEBUG. The panel renders in React's StrictMode; with the development build of React every effect mounts, unmounts and mounts again.
• Use WordPress's React. wp.element or window.React. A React copy bundled into your script breaks hooks.
• render must not return a DOM node. If you want to draw with plain DOM code, return an element with a ref callback and fill the node there.
• Collisions. Registering settings, library or upsell is ignored. Registering sets, audit, configurator or licence takes over a Pro tab. The last registration of an id wins.
• ctx values from PHP are not always typed. maxMbCeiling can be a string; the booleans are already converted.

Related

• window.EasySvgPanel
• easy_svg_panel_menu_tabs
• easy_svg_panel_enqueue
• window.EasySvgPanel.registerCollections()
• window.EasySvgPanel.api
• EASY_SVG_PANEL_API
• Build an add-on for the Icons panel