window.EasySvgPanel.api

JavaScript · Easy SVG · Status: Stable

window.EasySvgPanel.api tells your script which version of the panel contract the installed Easy SVG speaks. It is a plain number, the same as the PHP constant EASY_SVG_PANEL_API. Check it before you use a feature that a newer level added, and your add-on keeps working on sites that have not updated yet.

Usage

const level = Number( window.EasySvgPanel.api || 1 );

When to use it

• Before you call registerCollections(), which exists from level 3.
• Before you rely on area or a custom icon for a tab, which arrived with level 2.
• In an add-on that supports several Easy SVG versions and should degrade instead of breaking.

When not to use it:

• To compare plugin versions. The level changes only when the panel contract changes shape; many releases share one level.
• In PHP. There you read EASY_SVG_PANEL_API directly, for example before you add the easy_svg_panel_enqueue action.

Parameters

None. It is a read-only number on the registry object.

Return value

Default

1 when the panel's localized data carries no panelApi. On panels that are older than this property, window.EasySvgPanel.api is undefined, which is why the examples fall back to 1.

Examples

Read the level

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

if ( 0 === level ) {
	// Not on the Icons screen, or the panel did not load.
}

Use a level 3 feature only where it exists

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

	if ( 3 <= Number( panel.api || 1 ) ) {
		panel.registerCollections( {
			id: 'myaddon',
			load: () => [],
		} );
	}
} )();

Check the method, not just the number

For extra safety, combine the level with a type check. If a future level ever changed a method, the type check still keeps your script from throwing.

const panel = window.EasySvgPanel;
const canCollect =
	!! panel &&
	3 <= Number( panel.api || 1 ) &&
	'function' === typeof panel.registerCollections;

Decide in PHP whether to load the script at all

The same number exists on the server, so you can skip the enqueue on panels that are too old.

add_action( 'plugins_loaded', 'myaddon_boot' );

function myaddon_boot() {
	if ( defined( 'EASY_SVG_PANEL_API' ) && 3 <= (int) EASY_SVG_PANEL_API ) {
		add_action( 'easy_svg_panel_enqueue', 'myaddon_enqueue_panel' );
	}
}

How it works

1. In PHP, easy_svg_panel_assets() passes 'panelApi' => (int) EASY_SVG_PANEL_API to wp_localize_script() as part of window.EasySvgPanelData. The constant itself is used, so PHP and JavaScript cannot disagree.
2. wp_localize_script() turns scalar values into strings, so EasySvgPanelData.panelApi arrives as "3".
3. When the panel bundle installs the registry, it computes Number( EasySvgPanelData.panelApi || 1 ) once and stores the result as api.

The value is read once at install time. It does not change while the page is open.

Pitfalls

• Prefer api over EasySvgPanelData.panelApi. The localized value is a string, so '3' >= 3 works by coercion but '3' === 3 does not. api is already a number.
• undefined on very old panels. Always fall back, as in Number( panel.api || 1 ).
• Do not write to it. Changing the number does not add features; it only makes your own checks lie.
• The level is not the plugin version. Easy SVG 5.4.0 is level 3; do not derive one from the other.

Related

• EASY_SVG_PANEL_API
• window.EasySvgPanel
• window.EasySvgPanel.registerTab()
• window.EasySvgPanel.registerCollections()
• window.EasySvgPanelData
• easy_svg_panel_enqueue