Admin JavaScript hooks

The configurator editor is a Backbone application too. These hooks cover its views, the save pipeline, global layers, import/export, and the admin 3D preview.

They are all wp.hooks and need a namespace as the second argument. See the hook reference index for the mechanics.

Most of these are for add-ons that extend the editor itself. If you only want to add a field to a layer or a choice, the admin PHP settings filters are simpler and give you storage and translation for free.

Editor views

Saving

Global layers

Import and export

Choice selection

3D preview

PC.fe.models.layer.init and PC.fe.models.choice.init

Fire as each model is constructed, in the editor and on the frontend — the model layer is shared. Extra Price uses the choice hook at priority 30 to compute its display price.

wp.hooks.addAction( 'PC.fe.models.choice.init', 'my-plugin/admin', function ( model ) {	if ( ! model.get( 'my_field' ) ) {		model.set( 'my_field', '', { silent: true } );	}} );

Use { silent: true } when seeding defaults, or you will trigger a change event before the view exists.

PC.admin.layer_form.render.on.change.events and PC.admin.choice_form.render.on.change.events

A space-separated list of Backbone change events that cause the form to re-render. If you add a field whose presence depends on another field's value, add that field's change event here or your field will not appear until the panel is reopened.

wp.hooks.addFilter(	'PC.admin.choice_form.render.on.change.events',	'my-plugin/admin',	function ( events ) {		return events + ' change:my_field';	});

PC.admin.choices.save and PC.admin.choices.fetch

Both receive a handled callback as their third argument. Calling it tells the editor you have taken over that operation, and the default routine is skipped:

wp.hooks.addAction( 'PC.admin.choices.save', 'my-plugin/admin', function ( model, layerView, handled ) {	if ( ! model.get( 'my_external_source' ) ) return;	mySave( model ).then( function () {		handled();	} );} );

Only take over when you genuinely mean to. Calling handled() and then failing leaves the editor believing the save succeeded.

The batching filters

Large configurators are saved in batches so a single request does not exceed the server's POST limits or its execution time. Three filters tune that, and one sets the timeout:

// A slow shared host: smaller batches, longer timeout.wp.hooks.addFilter( 'mkl_pc_admin_layer_save_batch_max', 'my-plugin/admin', function () {	return 2;} );wp.hooks.addFilter( 'mkl_pc_admin.save_timeout', 'my-plugin/admin', function () {	return 60000;} );

Defaults are 5 layers per batch, 512 KB per content batch, and the Admin save timeout setting (30 seconds). Values must be positive integers — anything else falls back to the default.

Raising the batch sizes makes saving faster on a healthy server and makes it fail on a constrained one. If merchants report saves timing out on large products, lower them rather than raising the timeout.

mkl_pc_layer_save_global_use_default

Return false to stop the editor's own global-layer save from running, leaving the work to your PC.admin.layer.saveGlobal handler.

wp.hooks.addFilter(	'mkl_pc_layer_save_global_use_default',	'my-plugin/admin',	function ( useDefault, layerModel ) {		return layerModel.get( 'my_external' ) ? false : useDefault;	});

PC.fe.import.collections

Which collections a configuration import covers, [ 'layers', 'content', 'angles', 'conditions' ] by default. Add your own key and the importer will walk it, provided the export produced it.

wp.hooks.addFilter( 'PC.fe.import.collections', 'my-plugin/admin', function ( collections ) {	collections.push( 'my_collection' );	return collections;} );

See Importing and exporting a configuration for what the format looks like.

PC.choices.comparator

The Backbone comparator used to sort choices, sorting by the order attribute by default.

wp.hooks.addFilter( 'PC.choices.comparator', 'my-plugin/admin', function ( comparator ) {	return function ( choice ) {		return choice.get( 'name' ).toLowerCase();	};} );

This affects the editor and the frontend. Sorting by anything other than order means shop managers can no longer arrange choices by dragging them.

PC.admin.3d_settings.three_ready and …viewer_ready

The admin 3D preview's equivalents of the frontend runtime hooks. three_ready hands you the loaded modules — THREE, OrbitControls, loadEnvMap, setSceneEnvironment, FakeShadow and the postprocessing creator — before a scene exists. viewer_ready fires once it does, with the view, its internal scene bag and THREE.

wp.hooks.addAction( 'PC.admin.3d_settings.viewer_ready', 'my-plugin/admin', function ( view, three, THREE ) {	three.scene.add( new THREE.AxesHelper( 1 ) );} );

These mirror, but are not the same as, the frontend's PC.fe.viewer.runtime.ready. The admin preview has no runtime API object — see The 3D runtime API for the frontend equivalent.

mkl_pc_get_icon_html and mkl_pc_admin_nav_icon

Editor icon rendering. mkl_pc_get_icon_html receives the rendered markup, the icon id and the options; mkl_pc_admin_nav_icon supplies the icon for a nav item by menu id.

wp.hooks.addFilter( 'mkl_pc_admin_nav_icon', 'my-plugin/admin', function ( icon, menuId ) {	return 'my_tab' === menuId ? '<span class="dashicons dashicons-star-filled"></span>' : icon;} );

Register SVGs through the PHP filter mkl_pc_admin_icon_registry so they are available by id.