1. Home
  2. Docs
  3. 3D
  4. Extend Modules
  5. Inspiration Gallery

Inspiration Gallery

The Inspiration Gallery module (inspiration-gallery, shown as Inspiration Gallery on wp3dconf → Modules) gives a configurator a set of ready-made looks. Each inspiration has a name, a thumbnail and a choice of options, shown as a row of thumbnails under the canvas; visitors apply a look with one click, then change it further or undo it. How a shop owner sets them up is in inspiration-gallery.md.

Pro only. The module is listed in build-scripts/build-lite.php‘s strip list and required from pro/class-wp3dconf.php, so it is not in the Lite package.


Overview

PieceWhere
PHP bootstrap, validation, payloads, import remapmodules/inspiration-gallery/class-inspiration-gallery.php
Editor dialog (Vue)common/_dev/modules/inspiration-gallery/ → built to modules/inspiration-gallery/assets/editor/
Frontend markup (theme-overridable)templates/inspiration-gallery.php
Frontend Alpine componentmodules/inspiration-gallery/assets/frontend/js/ (hand-written ES modules, not bundled)
Frontend stylingmodules/inspiration-gallery/assets/frontend/inspiration-gallery.css
Applying a configurationapplyConfiguration() on the host store, common/_dev/frontend/stores/index.js

How it behaves on the frontend

  • The gallery is printed in the canvas column, after the canvas, in every skin. It shows only when the configurator has inspirations and the page has not hidden it with show_inspiration, and only once the configurator is ready, so it never flashes on load or shows without JavaScript.
  • The row scrolls sideways when the cards do not fit. On devices with a mouse, ‹ › arrows scroll it most of a width at a time and show only while there is more on that side; touch screens swipe and show no arrows.
  • Each card’s price is what the configuration would cost once applied (defaults filled in, missing options dropped), worked out with store.priceConfiguration() without applying anything, and again whenever the configurator’s price changes.
  • Undo restores the configuration from before the first apply, even after several. Any option the visitor picks themselves clears the applied state and Undo.

What “apply” does

Applying goes through store.applyConfiguration(), which changes the selection the same way clicks would:

  • Everything leaving is deactivated first, then everything new is activated, so a swapped mesh is put back before its replacement goes on.
  • A group the inspiration does not list gets its default. A listed group gets exactly the listed options that still exist; a single-choice group keeps only one; a required group that would end up empty falls back to its default.

Data

Stored shape

Post meta _wp3dconf_inspirations:

array(
  'version' => 1,
  'items'   => array(
    array(
      'id'            => 'insp_ab12cd',
      'name'          => 'Midnight Edition',
      'thumbnail_id'  => 123,
      'active_layers' => array( 'groupUid' => array( 'optionUid' ) ),
    ),
  ),
)

active_layers is the same { parentUid: [childUid] } shape the frontend store and shareable links use.

The heading is the wp3dconf_inspiration_heading_text option, read with Inspiration_Gallery::get_heading().

Validation

Inspiration_Gallery::normalize() runs on save and again whenever the data is read, so a configurator that arrived through an import is cleaned the same way:

  • An item with a missing or duplicate id is dropped. Names are sanitized, capped at 100 characters, and fall back to Untitled.
  • A thumbnail that is not an image attachment becomes 0; the item is kept without one.
  • A selection is kept only while the option is still a child of that group in the current model structure, so deleting an option in the editor quietly removes it from every inspiration.
  • A single-choice group keeps only the last option.

Payloads

WhereKeyContents
Editorwindow.wp3dconfEditorData.inspirationGalleryiconId, items (stored shape plus a thumbnail_url for the preview), i18n
Frontendwindow.WP3dConf.inspirationGalleryheading, and items: { id, name, thumbnail, activeLayers }. thumbnail is the medium size URL. Not printed when there are no inspirations or the gallery is switched off.

Export, import, duplicate and templates

  • On save, each thumbnail’s URL is added to the configurator’s _wp3dconf_attachment_urls, the list of images an export carries.
  • On import, and when creating a configurator from a template, those images are sideloaded like any other. The module then swaps each thumbnail_id for the new attachment through the wp3dconf/import/remap_attachments filter. A thumbnail that could not be sideloaded is cleared rather than left pointing at an unrelated image on the new site. This runs even when the module is disabled on that site.
  • Duplicate copies the meta on the same site, so thumbnails stay as they are.

Customising

Template

Copy templates/inspiration-gallery.php to your-theme/wp3dconf/<plugin-slug>/inspiration-gallery.php. Keep:

  • data-wp3dconf-inspiration, hidden and x-ignore on the root, and its x-data="wp3dconfInspirationGallery";
  • x-ref="list" and x-on:scroll.passive="updateScroll()" on the row, if you keep the arrows;
  • x-ref="undoText" and its data-template on the Undo text;
  • the price markup inside each card (wp3dconf-inspiration-price and its x-bind:hidden / x-text calls), or leave it out to show no prices;
  • data-id on each card.

The template receives $args['heading'] (plain text, may be empty), $args['items'] (the frontend items above), $args['config_id'] and $args['skin']. It is printed inside the canvas wrapper, after the canvas, on wp3dconf/frontend/canvas/after_canvas.

Styling

The cards, Undo and the arrows are <button>s for keyboard and screen reader use, but every theme style on them (background, border, padding, hover and focus) is reset with all: unset in every state, and only the gallery’s own look is drawn back. The only state style is a focus ring for keyboard users (:focus-visible), which a mouse click or tap never shows. Colours and the card width are CSS variables on .wp3dconf-inspiration:

.wp3dconf-inspiration {
  --wp3dconf-inspiration-bg: #fff;
  --wp3dconf-inspiration-text: #1e1e1e;
  --wp3dconf-inspiration-muted: #6b6b6b;
  --wp3dconf-inspiration-accent: #1e1e1e;
  --wp3dconf-inspiration-card-width: 132px; /* 112px on screens 600px wide or narrower */
}

With prefers-reduced-motion, the arrows jump instead of scrolling smoothly.

Applying a configuration from your own code

applyConfiguration() is on the host store, so any script can use it:

const store = Alpine.store( `wp3dconf_${ WP3dConf.postId }` );

// Returns the configuration it replaced.
const previous = store.applyConfiguration( { activeLayers: { groupUid: [ 'optionUid' ] } } );

// Later: put it back.
store.applyConfiguration( previous );

store.getConfiguration() returns a copy of the current selection in the same shape, and store.priceConfiguration( { activeLayers } ) returns { total, regularPrice } for a configuration without applying it. See hooks-frontend.md for wp3dconf/frontend/configuration/applied.

How the frontend starts

The frontend files are native ES modules loaded with wp_enqueue_script_module(), which run after the host has started Alpine. The component therefore can’t be found on Alpine’s first pass, so the root is printed with x-ignore. mountGallery() in gallery.js registers the component, removes the ignore and starts just that element with Alpine.initTree().


Hooks

Every part of the feature can be extended without editing the plugin. PHP hooks are standard WordPress hooks. JavaScript hooks use the host hook bus, window.WP3dConf.addAction() / addFilter(), in the editor and on the frontend.

PHP filters

PHP actions

ActionArgumentsFires
wp3dconf/inspiration_gallery/saved$post_id, $inspirationsAfter the inspirations were saved from the editor.
wp3dconf/inspiration_gallery/deleted$post_idAfter the last inspiration was removed.
wp3dconf/inspiration_gallery/before_list$items, $config_idIn the gallery, under the heading and before the row.
wp3dconf/inspiration_gallery/after_list$items, $config_idIn the gallery, after the row.
wp3dconf/inspiration_gallery/card_after_name$item, $config_idInside each card, after the name and price. The card is a <button>: print escaped phrasing content only, such as a <span>.

Frontend (JavaScript)

Every hook gets a context object with store (the configurator’s Alpine store) and gallery, the control API below; hooks about one inspiration also get item (the frontend item, including keys added in PHP).

HookTypeValue / argumentsUse it to
wp3dconf/frontend/inspiration/readyaction{ gallery, store }Keep the API, e.g. to apply an inspiration from a link.
wp3dconf/frontend/inspiration/can_applyfiltertrue, { item, store, gallery }Return false to stop an inspiration being applied.
wp3dconf/frontend/inspiration/configurationfilter{ activeLayers }, { item, store, gallery }Change what is applied. Add customData to set a Custom Text or other layer’s data.
wp3dconf/frontend/inspiration/appliedaction{ item, configuration, previous, store, gallery }React to an apply, e.g. for analytics.
wp3dconf/frontend/inspiration/undoneaction{ configuration, store, gallery }React to Undo. configuration is what was put back.
wp3dconf/frontend/inspiration/undo_textfilterstring e.g. “Night applied”, { item, store, gallery }Change the text before Undo, plain text, or return false to show no Undo.
wp3dconf/frontend/inspiration/pricefilter{ total, regularPrice }, { item, store, gallery }Change a card’s price, or return false to show none.

The gallery API:

MemberDoes
apply( id )Apply an inspiration, through the same filters as a click. Returns whether it was applied.
undo()Put back the configuration from before the first apply.
activeId()The applied inspiration’s id, or ''.
refreshPrices()Work the card prices out again.
itemsThe inspirations, a Map by id.
rootThe gallery’s root element.

Register frontend hooks on the wp3dconf/frontend:ready window event, as for every other frontend hook; the gallery starts after it, on DOMContentLoaded, so ready is never missed.

window.addEventListener( 'wp3dconf/frontend:ready', () => {
  const { addAction, addFilter } = window.WP3dConf;

  // Apply an inspiration from a link such as #inspiration=night.
  addAction( 'wp3dconf/frontend/inspiration/ready', ( { gallery } ) => {
    const match = window.location.hash.match( /inspiration=([\w-]+)/ );

    if ( match ) {
      gallery.apply( match[ 1 ] );
    }
  } );

  // Set a layer's custom data with the look (its shape depends on the layer type).
  addFilter( 'wp3dconf/frontend/inspiration/configuration', ( configuration, { item } ) => {
    if ( item.engraving ) {
      configuration.customData = { textLayerUid: { text: item.engraving } };
    }

    return configuration;
  } );
} );

Editor (JavaScript)

HookTypeValue / argumentsUse it to
wp3dconf/editor/inspiration/fieldsfilter[]Return Vue components to render under the selections. Each gets the selected inspiration as item (edit it in place) and the dialog’s i18n. Read each time the dialog opens.
wp3dconf/editor/inspiration/new_itemfilterthe new itemSet your fields’ defaults. The id cannot be changed.
wp3dconf/editor/inspiration/groupsfilter[ { uid, label, multiple, options } ], model structureOffer other layers in the selection rows, or hide groups.
wp3dconf/editor/inspiration/payloadfilter{ items }Change what is sent on save. Keep extra item fields on the PHP item filter or they are dropped.
wp3dconf/editor/inspiration/item_added / item_removedactionthe itemReact to an inspiration being added or deleted.
wp3dconf/editor/inspiration/savedactionthe itemsReact to a successful save.

Example: a badge on each card

// Keep the field on save and read.
add_filter( 'wp3dconf/inspiration_gallery/item', function ( $item, $raw ) {
	$item['badge'] = isset( $raw['badge'] ) && is_scalar( $raw['badge'] ) ? sanitize_text_field( (string) $raw['badge'] ) : '';
	return $item;
}, 10, 2 );

// Send it to the frontend.
add_filter( 'wp3dconf/inspiration_gallery/frontend_item', function ( $frontend_item, $item ) {
	$frontend_item['badge'] = $item['badge'] ?? '';
	return $frontend_item;
}, 10, 2 );

// Print it on the card.
add_action( 'wp3dconf/inspiration_gallery/card_after_name', function ( $item ) {
	if ( ! empty( $item['badge'] ) ) {
		echo '<span class="my-badge">' . esc_html( $item['badge'] ) . '</span>';
	}
} );

In the editor, a component returned from wp3dconf/editor/inspiration/fields edits item.badge, and it is saved with the rest.


Limitations

  • The editor cannot set custom data, such as a Custom Text layer’s text or a Custom Image Upload image, and only lists option layers. Other layers follow their group’s default: one that is on by default stays on with the visitor’s text or image, and one that is not is switched off. Code can still set custom data through the wp3dconf/frontend/inspiration/configuration filter.
  • The thumbnail is uploaded by hand; the editor cannot capture one from the canvas yet.
  • A card’s price uses the visitor’s current custom data and does not run conditional logic, so a layer that a rule would change once the look is applied is priced as listed.

How can we help?