Frontend JavaScript hooks

The configurator is a Backbone application. These hooks let you follow its lifecycle, change the data each view renders from, substitute views entirely, and shape the payload that eventually reaches the cart.

All of them use wp.hooks and need a namespace as the second argument. See the hook reference index for the mechanics.

Lifecycle

Layers

Choices

Viewer

Saving and add to cart

Configuration loading

Steps, summary and navigation

Tooltips

3D

PC.3d.postprocessingPasses, PC.3d.createPostprocessingLayer, PC.3d.postprocessingEnabled and the PC.fe.viewer.runtime.* events are documented in The 3D runtime API.

PC.fe.start

The one to reach for by default. It fires once the configurator is open, its data is loaded and its views exist — everything on PC.fe is safe to touch.

wp.hooks.addAction( 'PC.fe.start', 'my-plugin/configurator', function ( view ) {	console.log( PC.fe.layers.length, 'layers' );	console.log( PC.fe.currentProductData.product_info );} );

PC.fe.init fires much earlier, before the data has arrived. Add-ons commonly register at priority 30 here to run after core's own setup.

PC.fe.configurator.choice_data and PC.fe.configurator.layer_data

Filter the attributes a template renders from. This is the right place to compute a display value without changing the underlying model.

wp.hooks.addFilter(	'PC.fe.configurator.choice_data',	'my-plugin/configurator',	function ( attributes ) {		attributes.badge = attributes.stock > 0 ? '' : 'Made to order';		return attributes;	});

Anything you add is available in the template as data.badge — pair it with tmpl-pc-configurator-choice-item to print it. template_choice_data runs after this, immediately before rendering, and is where WPML-style translation is applied.

Do not mutate the model here. These filters run on every render; setting model attributes from them causes render loops.

PC.fe.choice.set_choice

Fires whenever a choice is selected, with the model and the view. This is the main "customer did something" signal.

wp.hooks.addAction( 'PC.fe.choice.set_choice', 'my-plugin/configurator', function ( model, view ) {	myAnalytics.track( 'choice', {		layer:  model.get( 'layerId' ),		choice: model.get( 'name' ),	} );} );

Conditional Logic hooks this to re-evaluate its rules, so by the time your callback runs the rest of the configurator may not have caught up yet. If you need the settled state, use mkl_checked_conditions from the Conditional Logic add-on, or defer a frame.

PC.choices.canSelectChoice

Return false to refuse a selection. This is a real veto — the choice is not activated and the configurator logs the refusal.

wp.hooks.addFilter(	'PC.choices.canSelectChoice',	'my-plugin/configurator',	function ( canSelect, choice, collection, context ) {		if ( choice.get( 'requires_login' ) && ! myUserIsLoggedIn ) {			return false;		}		return canSelect;	});

Give the customer some feedback when you refuse, or the click appears to do nothing.

PC.fe.save_data.choices and the parse filters

The payload sent to the cart is built by walking every layer. Four filters shape it:

1. PC.fe.save_data.parse_choices.add_choice — include this choice at all?
2. PC.fe.save_data.parse_choices.added_choice — its data
3. PC.fe.save_data.parse_choices.add_layer_group / …added_group_layer — the same for groups
4. PC.fe.save_data.choices — the finished array

Two more record the context a choice was made in, so the saved configuration can be rendered later without re-reading the product: …parse_choices.angle_id for the angle, and …parse_choices.image_order for the layer's position in the merged image. The latter defaults to the layer's image_order, or to its order where none is set, which is what keeps a saved configuration stacking correctly after the product's layers are reordered.

wp.hooks.addFilter(	'PC.fe.save_data.parse_choices.added_choice',	'my-plugin/configurator',	function ( choiceData, choice ) {		choiceData.my_reference = choice.get( 'my_reference' );		return choiceData;	});

Anything you add here reaches the server. It must survive mkl_pc_db_fields — a key that is not on that allowlist is dropped on save.

What you add is also what a cart item or an order line reads back later, rather than looking the value up on the product again — see mkl_pc/choice/source.

PC.fe.save_data.before_save.promises

Push a promise onto the array and add-to-cart waits for it before building the payload. This is how Text Overlay exports its rendered PNG and how the 3D viewer captures its screenshot.

wp.hooks.addFilter(	'PC.fe.save_data.before_save.promises',	'my-plugin/configurator',	function ( promises ) {		promises.push( myAsyncExport() );		return promises;	});

Every promise here delays add-to-cart, so keep them fast and make sure they always settle — a promise that never resolves hangs the button for good.

PC.fe.validate_configuration

Filters the array of validation errors before the configurator decides whether to submit. Push an entry to block add-to-cart with your own message.

wp.hooks.addFilter( 'PC.fe.validate_configuration', 'my-plugin/configurator', function ( errors ) {	if ( ! myRequirementMet() ) {		errors.push( { message: 'Please choose a finish before continuing.' } );	}	return errors;} );

PC.fe.viewer.main_view and PC.fe.viewer.item.view

Substitute view classes. main_view swaps the whole viewer — this is how the 3D viewer replaces the 2D one:

wp.hooks.addFilter( 'PC.fe.viewer.main_view', 'my-plugin/viewer', function ( View ) {	return PC.fe.currentProductData.my_flag ? MyViewerView : View;} );

item.view swaps the view for an individual layer image, and receives the model, so you can substitute per layer:

wp.hooks.addFilter(	'PC.fe.viewer.item.view',	'my-plugin/viewer',	function ( View, model, viewer ) {		return 'video' === model.get( 'my_media_type' ) ? MyVideoLayerView : View;	});

PC.fe.layer.beforeRenderChoices

Fires just before a layer builds its choices, which makes it the point at which a layer type can substitute its own choices view. Both Multiple Choice and Text Overlay work this way:

wp.hooks.addAction(	'PC.fe.layer.beforeRenderChoices',	'my-plugin/layers',	function ( layerView ) {		if ( 'my_type' !== layerView.layer_type ) return;		layerView.choices = new MyChoicesView( {			content: PC.fe.getLayerContent( layerView.model.id ),			model:   layerView.model,		} );	});

Pair it with mkl_pc_layer_types so the type is selectable in the admin.

PC.fe.add_to_cart.before and …append_ajax_request_body

before fires as add-to-cart starts. append_ajax_request_body receives the request body so you can add fields — note it is an action: mutate the object, do not return it.

wp.hooks.addAction(	'PC.fe.add_to_cart.append_ajax_request_body',	'my-plugin/cart',	function ( body, view ) {		body.append( 'my_field', document.querySelector( '#my-field' ).value );	});

PC.fe.trigger_add_to_cart can cancel the request outright by returning false.

PC.fe.setConfig and friends

Fire when a stored configuration is applied — restoring a cart item, an order, or a saved design. setConfig.before runs before the reset, setConfig.setItem per item, setConfig at the end.

wp.hooks.addAction( 'PC.fe.setConfig', 'my-plugin/configurator', function ( configItems ) {	myRestoreExtras( configItems );} );

PC.fe.is_setting_config is true throughout, which is how you tell a restored selection from a customer's click inside a set_choice handler.

PC.fe.tooltip.options

Every configurator tooltip passes through here as a Tippy.js options object.

wp.hooks.addFilter( 'PC.fe.tooltip.options', 'my-plugin/tooltips', function ( options, view ) {	options.theme = 'my-theme';	options.delay = [ 200, 0 ];	return options;} );

Add-ons layer their own filter on top — PC.fe.choice.tooltip.options, PC.fe.advanced-description.tooltip.options, PC.fe.text-overlay.tooltip.options — so this one is the place for a change that should apply everywhere.

PC.fe.choices.where and PC.fe.close_choices_after_selection

Layout behaviour. where decides where a layer's choices list is inserted ('in' or 'out'); close_choices_after_selection decides whether picking one closes the list, defaulting to the matching plugin setting.

wp.hooks.addFilter(	'PC.fe.close_choices_after_selection',	'my-plugin/configurator',	function ( close, model ) {		return 'multiple' === model.collection.layer_type ? false : close;	});

PC.fe.viewer.layer.classes and PC.fe.viewer.item.tag

classes filters the class list on a viewer layer; item.tag changes the element a layer image renders as, 'img' by default.

wp.hooks.addFilter( 'PC.fe.viewer.layer.classes', 'my-plugin/viewer', function ( classes, view ) {	classes.push( 'layer-' + view.model.get( 'layerId' ) );	return classes;} );

PC.fe.viewer.layers.preload.complete

Fires once every layer image has preloaded — the right moment to take a screenshot, measure the viewer, or reveal something that was waiting on a complete render.

Dynamic 3D hooks

The 3D viewer mirrors each of its events onto a hook name built at runtime. Those are covered in The 3D runtime API.