window.EasySvgPanel

The global registry on the Icons screen through which add-ons add tabs and icon collections to the Easy SVG panel and read its contract level.

JavaScript · Easy SVG · Status: Stable

window.EasySvgPanel is the one global object an add-on talks to when it extends the Icons panel. The panel creates it on the Icons screen before it draws anything. Your script registers tabs and icon collections on it, and the panel picks them up, whether you register before or after its first render.

Usage

window.EasySvgPanel;

// Members an add-on may rely on:
window.EasySvgPanel.api; // number, the panel contract level
window.EasySvgPanel.registerTab( tab );
window.EasySvgPanel.registerCollections( provider ); // level 3

When to use it

In a script you enqueue through easy_svg_panel_enqueue, to add a tab or a collection provider.
To find out which contract level the installed panel speaks, through api.

When not to use it:

On any screen other than Icons. The object exists only where the panel bundle runs.
To build features on get(), list(), subscribe() or collectionProviders(). They exist, the panel itself uses them, but the readme does not name them as part of the add-on contract, so they may change.
To pass data from PHP to your script. Use your own handle with wp_add_inline_script() for that.

Parameters

None. window.EasySvgPanel is an object, not a function. Its members are listed below.

Return value

apinumber

The panel contract level, the same number as the PHP constant EASY_SVG_PANEL_API. Read once, when the registry is installed. See window.EasySvgPanel.api.

registerTabfunction

Adds or replaces a tab. Takes one object with at least id and a render function. See window.EasySvgPanel.registerTab().

registerCollectionsfunction

Adds or replaces an icon collection provider for the Icon library tab. Takes one object with at least id and a load function. Contract level 3. See window.EasySvgPanel.registerCollections().

get, list, subscribe, collectionProvidersfunction

Used by the panel itself: get( id ) returns a registered tab or undefined, list() and collectionProviders() return new arrays of what was registered, subscribe( fn ) calls fn after every registration and returns a function that unsubscribes. Not part of the promised add-on surface.

Default

undefined until the panel bundle has run. On the Icons screen it is installed by the very first statement of build/panel.js, so any script that depends on the panel handle sees it.

Examples

Check that the registry is there

A script that may also be loaded elsewhere (for example by a build tool that bundles several entry points) should leave quietly when there is no panel.

( function () {
	const panel = window.EasySvgPanel;

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

	// Safe to register from here on.
} )();

One bundle, one tab and one collection

An add-on can use both extension points from the same file. The tab component uses wp.element, which is the React instance WordPress ships and the panel uses too.

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

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

	function ReportTab() {
		return el( 'p', null, __( 'Nothing to report yet.', 'myaddon' ) );
	}

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

	if ( 'function' === typeof panel.registerCollections ) {
		panel.registerCollections( {
			id: 'myaddon',
			load: () => Promise.resolve( [] ),
		} );
	}
} )();

Load the script the right way (PHP)

The registry exists when your script runs only because your script depends on the panel handle.

add_action( 'easy_svg_panel_enqueue', 'myaddon_enqueue_panel' );

function myaddon_enqueue_panel( $handle ) {
	wp_enqueue_script(
		'myaddon-panel',
		plugins_url( 'assets/panel.js', __FILE__ ),
		array( $handle, 'wp-element', 'wp-i18n' ),
		'1.0.0',
		true
	);
}

How it works

The registry is defined in src/panel/registry.js and installed by installRegistry(), which src/panel/main.jsx calls before it creates the React root.

Installed once. If window.EasySvgPanel already exists with the internal flag __installed, nothing happens. Otherwise a fresh object is created with two private maps (tabs and collection providers, both keyed by id) and a set of listeners.
Validation is minimal. registerTab() stores the object only when it has an id and a render function, registerCollections() only when it has an id and a load function. Anything else is ignored without an error. A second call with the same id replaces the first.
Your object is stored as is. Unknown fields are kept; the panel reads only the fields it understands.
Every registration notifies. Listeners are called one by one, and a listener that throws is caught so registration continues.
The panel listens. The main panel component subscribes on mount and re-renders on every notification. It also re-reads the registry once right after subscribing, so a registration that landed between its first render and the subscription is not lost. The Icon library tab subscribes too and reloads all collection providers on every notification.

Pitfalls

Do not assign to window.EasySvgPanel. If an object with __installed set is already there, the panel skips its own installation and uses yours, which breaks the panel for every add-on on the site.
Do not bundle registry.js or your own copy of React. Use the global object, and wp.element or window.React for elements. A second React copy makes hooks fail with "Invalid hook call".
Ids are shared by all add-ons. Prefix them with your add-on's slug, for both tabs and collection providers.
Silent failures. A missing render or load is ignored without a message. If your tab does not show, log window.EasySvgPanel.get( 'your-id' ) in the browser console first.
The object exists only on the Icons screen, and only when build/panel.js was loaded.

Everything registered here runs with the rights of the logged-in user on an admin screen. Do not inject markup from untrusted sources into the panel, and treat every server call your code makes as public: the server has to check capabilities and the wp_rest nonce, not the registry.

Was this page helpful?