Creating a custom theme

A configurator theme is a folder with a style.css file, registered with the plugin. It is not a WordPress theme: it only styles the configurator the customer sees.

The fastest way to make one is the custom theme starter. It is a small WordPress plugin that registers a theme called My theme (mytheme), with a copy of the Default theme's CSS.

Using the starter

1. Download or clone product-configurator-custom-theme.
2. In WordPress, go to Plugins > Add New > Upload Plugin and upload the zip (or copy the folder into wp-content/plugins).
3. Activate it.
4. The theme appears in Product Configurator > Settings, under Configurator theme, like any built-in theme. Select it and save.

Edit my-theme/style.css to match the shop. The starter also includes style.scss if you prefer Sass; compile it back to style.css, which is the file the plugin loads.

Registering the theme

Registration happens on mkl_pc_is_loaded, once the Product Configurator is available. The starter does this in product-configurator-theme.php:

function my_product_configurator_custom_theme_init() {	if ( function_exists( 'mkl_pc' ) && is_callable( [ mkl_pc( 'themes' ), 'register_theme' ] ) ) {		// 'mytheme' is the theme ID.		// 'my-theme' is the folder that contains style.css.		mkl_pc( 'themes' )->register_theme( 'mytheme', plugin_dir_path( __FILE__ ) . 'my-theme' );	}}add_action( 'mkl_pc_is_loaded', 'my_product_configurator_custom_theme_init' );

Two names matter:

• mytheme — the theme ID. Used by mkl/pc/theme_id and mkl_pc( 'settings' )->get_theme(). It must be unique: it cannot match a built-in ID such as float or default.
• my-theme — the folder that holds style.css. Rename it if you like, and update the path passed to register_theme().

The name shown in the settings picker comes from style.css, not from either of those.

register_theme() returns a WP_Error if the ID is already taken, if the folder is missing, or if style.css is not in it.

The theme folder

A theme must contain style.css. Everything else is optional.

The stylesheet header

The plugin reads WordPress-style headers from style.css:

/*!Theme Name:   My themeDescription:  A descriptionTags:         right selector, right sidebarSupports: columns, color_swatches, steps*/

• Theme Name and Description appear in the settings picker.
• Tags are shown in the picker as a hint (layout, sidebar side, and similar).
• Supports is a comma-separated list of features. Only list what the CSS actually implements, or the matching settings will appear in the editor without working on the front.

Known Supports values:

• steps
• color_swatches
• columns
• display mode: full screen
• display mode: compact list
• extend_under_toolbar — lets a 3D canvas stretch under the toolbar

Preview image

Add a preview.png next to style.css to show a thumbnail in the picker.

theme.php

If theme.php is present, it is loaded only while this theme is the active one. Use it for theme-specific hooks and scripts: wrapping choice markup, enqueueing a JS file, adding Customizer colours.

The Float theme.php is a working example. A typical start is enqueueing a script when the configurator loads:

function mytheme_scripts() {	wp_enqueue_script(		'mkl/pc/themes/mytheme',		plugin_dir_url( __FILE__ ) . 'mytheme.js',		[ 'wp-hooks', 'jquery' ],		filemtime( plugin_dir_path( __FILE__ ) . 'mytheme.js' ),		true	);}add_action( 'mkl_pc_scripts_product_page_after', 'mytheme_scripts', 20 );

Markup inside the configurator is customised with the template hooks.

Starting from an existing theme

To kickstart from Float, WSB or another built-in theme instead of Default:

1. Copy the files from inc/themes/{id}/ in the Product Configurator plugin into my-theme.
2. Change Theme Name (and Description) in style.css or style.scss.
3. Keep a unique ID in register_theme() — do not reuse float or the other built-in IDs.
4. Recompile SCSS to style.css if you edit the Sass.

The built-in themes page lists each layout and which features it supports.

Selecting the theme

Once registered, choose it like any other theme in Product Configurator > Settings. To use it on some products only, see Using different themes on different products.