window.EasySvgPanel.registerCollections()

JavaScript · Easy SVG · Status: Stable

registerCollections() lets your add-on show its own icons in Easy SVG's Icon library tab. You hand over a provider: an object with an id and a load function that returns your collections. The library lists them in its sidebar, puts their icons into the same grid and search as the site's own icons, and offers editing actions only for what your provider implements.

Usage

window.EasySvgPanel.registerCollections( {
	id: 'myaddon', // required
	load: ( { signal } ) => Promise.resolve( collections ), // required

	// All optional:
	move, create, rename, trash,
	relabel, remove, add, recolour, replaceDrawing,
	importFile, addMedia,
	history, restoreVersion,
	exportIcons, exportMax,
	hint,
} );

When to use it

• Your add-on has icons of its own (a theme folder, a bundled icon set, sets stored in a custom post type) and people should find them where they already look for icons.
• You want the library's search, grid and copy buttons for those icons without building a tab.
• Your add-on works on sites with the free plugin alone. Unlike registerTab(), collections are not tied to an Easy SVG Pro licence.

When not to use it:

• To render icons on the front end. That is easy_svg_icon() and the easy_svg_icon_markup filter in PHP. The panel only displays what you hand it.
• To change the site's own library icons. Those belong to Easy SVG's REST routes.
• When the panel is older than contract level 3: the method does not exist there.

Parameters

Return value

Default

No providers are registered by the free plugin. Without readonly, a collection counts as writable, but the library still offers only the actions whose methods exist.

Examples

A read-only collection from inline data

The minimum: one collection, two icons, nothing editable. The markup here is static and already clean.

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

	const icons = [
		{
			key: 'myaddon-brand/logo',
			slug: 'logo',
			ref: 'myaddon-brand/logo',
			label: 'Logo',
			content: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/></svg>',
		},
		{
			key: 'myaddon-brand/mark',
			slug: 'mark',
			ref: 'myaddon-brand/mark',
			label: 'Mark',
			content: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 20 12 4l8 16z"/></svg>',
		},
	];

	panel.registerCollections( {
		id: 'myaddon',
		load: () => [ { id: 'myaddon-brand', label: 'Brand', readonly: true, icons } ],
	} );
} )();

Load collections from your REST route

A real provider asks the server, passes the abort signal on and caches the answer, because load() runs every time the library opens and every time anything is registered.

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

	const config = window.EasySvgPanelData || {};
	let cache = null;

	function request( path, options = {} ) {
		return fetch( config.restRoot + 'myaddon/v1' + path, {
			credentials: 'same-origin',
			...options,
			headers: {
				'Content-Type': 'application/json',
				'X-WP-Nonce': config.nonce,
			},
		} ).then( ( response ) =>
			response.json().then( ( data ) =>
				response.ok ? data : Promise.reject( new Error( data.message || response.statusText ) )
			)
		);
	}

	panel.registerCollections( {
		id: 'myaddon',
		load: ( { signal } ) => {
			if ( cache ) {
				return Promise.resolve( cache );
			}
			return request( '/collections', { signal } ).then( ( list ) => {
				cache = list;
				return list;
			} );
		},
		relabel: ( { ref, label } ) => {
			cache = null;
			return request( '/relabel', {
				method: 'POST',
				body: JSON.stringify( { ref, label } ),
			} );
		},
	} );
} )();

window.EasySvgPanelData is the panel's own localized data; reading restRoot and nonce from it saves you localizing them again. Your routes must answer { message } for actions and must check capabilities themselves.

Accept moves, with undo

move() receives refs of tiles from anywhere in the library. Return an undo when you can reverse the move.

window.EasySvgPanel.registerCollections( {
	id: 'myaddon',
	load: myaddonLoad,
	move: async ( { refs, to } ) => {
		const done = await myaddonPost( '/move', { refs, to } );
		return {
			message: done.message,
			undo: () => myaddonPost( '/move-back', { token: done.token } ),
		};
	},
} );

Defensive: only on contract level 3

( function () {
	const panel = window.EasySvgPanel;
	const level = panel ? Number( panel.api || 1 ) : 0;

	if ( 3 > level || 'function' !== typeof panel.registerCollections ) {
		return; // Older panel: no collections in the library.
	}

	panel.registerCollections( { id: 'myaddon', load: () => [] } );
} )();

How it works

The Icon library tab (src/panel/tabs/Library.jsx) does all the work:

1. When it loads. On mount, and again on every registry notification (any registerTab() or registerCollections() call), the tab aborts the previous load and calls load( { signal } ) on every provider, wrapped in Promise.resolve().
2. What it keeps. A result that is not an array counts as no collections, and a rejected Promise is swallowed the same way. Collections without an id or without an icons array are dropped. Each kept collection remembers its provider.
3. The sidebar. It appears once there is a collection, a provider with create or a hint. It lists All icons, Icon library, then every collection with its icon count. A hint from any provider is shown there.
4. The grid and the search. In All icons the library's icons and every collection's icons share one grid; selecting a collection shows only its icons. The search filters your icons in the browser by label, slug and ref. Tiles are keyed by key, else ref.
5. Drawing. Your content is drawn as markup after a second pass through DOMPurify with its SVG profile, as defence in depth.
6. Actions. An action appears only when your provider has the method and the collection is not readonly. The library waits for your Promise, shows its message (or "Done."), offers Undo when you returned undo, shows error.message when you rejected, and reloads all collections afterwards.

The library tab is only drawn for users who hold its capability (manage_options by default), and its content appears only while the icon library feature is switched on. When it is off, the tab shows a notice instead. Your load() is still called when the tab opens, but nothing of its answer is shown.

Pitfalls

• load() runs often. Every time the library opens and every time any add-on registers anything. Cache, and pass signal to your requests.
• Errors in load() vanish. A rejection simply shows no collections. Log the error yourself while developing.
• Collection ids must be unique across all providers and must not be all or library.
• Keep refs in the form collection/slug. When tiles are moved, refs that already start with the target id and a slash are skipped as "already there".
• Sanitize on the server. The panel's DOMPurify pass is a safety net, not your sanitizer. Clean markup with easy_svg_sanitizer() before you send it.
• readonly turns off everything for that collection, including moves into it.
• One exporter, one creator. If several providers implement exportIcons or create, only the first one registered is used.
• Off means off. With the icon library switched off in Settings, your collections are not shown at all, and your hint is not shown either, although load() still runs.

Related

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