Extra Variation Images

Each variation of a variable product can carry its own set of images, not just one. Pick a colour on the product page and the whole gallery changes, thumbnails included, instead of only the main image being replaced. This is built into Rey, so you do not need a separate variation images plugin.

Availability

The module ships with Rey and is enabled by default. It is listed as Extra Variation Images in Rey > Modules.

Where to find it

Edit a variable product, open the Variations tab and expand a variation. Right under the variation’s own image there is an Add Extra Images button.

Click it, select the images in the media library and press Add to Variation. The thumbnails appear in a row under the button. To remove one, click the thumbnail. The images are stored when you press Save changes, together with the rest of the variation data.

The variation’s own image stays what it is, the main image of the gallery. The extra images are added after it.

How the images are stored

From 3.3.1 the extra images are saved in WooCommerce’s own variation gallery field, the _product_image_gallery meta that WooCommerce maps to gallery_image_ids. Everything that reads a product through WooCommerce now sees them, the REST API, the CSV exporter, product feeds, ERP connectors and any other tool.

Before 3.3.1 Rey used a row of its own, rey_extra_variation_images, which only Rey knew how to read. That row is still read everywhere, so a site that updates keeps showing exactly the same galleries. It is moved to the WooCommerce field the first time you save that variation, one variation at a time. Nothing is rewritten on its own, a variation nobody edits keeps working off the old row for as long as you leave it alone.

Using WooCommerce’s own field instead

WooCommerce 11.1 has its own variation gallery field, called Variation gallery. Two fields writing to the same place would be confusing, so Rey hides WooCommerce’s one and shows its own.

If you would rather use WooCommerce’s field, turn the Extra Variation Images module off in Rey > Modules. WooCommerce’s Variation gallery field then appears in the Variations tab, and Rey keeps rendering the galleries on the product page the same way it did before. Only the editing field changes, the storefront does not.

The two fields work slightly differently. WooCommerce’s field is one ordered list and the first image in it becomes the variation’s main image, marked Primary. Rey’s field keeps the variation image where WooCommerce has always put it and adds the extra images next to it.

Three things worth knowing

A variation without its own image still shows a gallery

If a variation has no image of its own but has extra images, the first extra image becomes the main one. This matches what WooCommerce does with its own gallery, so a store moving over from the native field looks the same.

If a variation has neither, selecting it brings back the product’s default gallery.

The gallery is fetched at the first selection

Rey does not print every variation’s gallery into the page. A page with six variations and three images each would carry a lot of markup that most visitors never see. Instead, the gallery of a variation is requested once when the visitor first selects it, then kept in the browser for the rest of the visit and cached on the server for two weeks. The cache is cleared when you save the product.

The default variation is the exception. If your product has one preselected, its gallery is printed with the page, so there is no delay and no flicker on load.

A dedicated gallery plugin takes over completely

If WooCommerce Additional Variation Images or Additional Variation Images Gallery for WooCommerce is active, Rey steps aside entirely and lets the plugin render its own gallery. You get an admin notice pointing here. Deactivate the plugin to use Rey’s module, and read the migration section below first, so you keep the images you already have.

Migrating from another variation images plugin

If the site used another plugin before Rey, and products already have images stored by it, point Rey at that plugin’s storage with a snippet.

add_filter('reycore/module/extra_variation_images', function($settings){
	$settings['key'] = '_wc_additional_variation_images';
	return $settings;
});

For “Variation Images Gallery for WooCommerce” by RadiusTheme, use rtwpvg_images as the key instead. Rey reads that row and shows the images, so you can deactivate the old plugin without losing anything.

One thing to keep in mind since 3.3.1. The first time you save a variation, its images move into WooCommerce’s own field and the old plugin’s row is dropped. That is on purpose, so the images end up in one place, but it means going back to the old plugin later will not find them. If you want to keep that door open, migrate the images and leave the variations alone, or take a database backup before you start editing.

Importing and exporting

WooCommerce’s own product CSV export and import are supported. The column is called Rey Variations extra images and holds the image URLs separated by commas. Since 3.3.1 the extra images also show up in WooCommerce’s standard Images column for variation rows, because they are stored in WooCommerce’s own field now.

For WP All Import and similar tools, the meta key to write is _product_image_gallery on the variation, holding a string of attachment IDs separated by commas, for example 101,102,103. This used to be rey_extra_variation_images. The new key is WooCommerce’s own, so an import tool that already supports variation galleries needs no extra work.

For developers

Turn the module off in code, whatever the Modules screen says.

add_filter('reycore/module/extra-variation-images/enable', '__return_false');

On the storefront, Rey answers an empty gallery to WooCommerce, since the markup WooCommerce builds from it is never used and would only weigh the page down. If a storefront request does need to read it, a product feed for instance, lift it for that request.

add_filter('reycore/extra_variation_images/hide_native_gallery', function($hide){
	return is_feed() ? false : $hide;
});

Stop printing the default variation’s gallery markup with the page. The gallery is then fetched over ajax like any other variation.

add_filter('reycore/module/extra_variation_images', function($settings){
	$settings['default_variation_direct_replacement'] = false;
	return $settings;
});

Put these in the child theme’s functions.php or in a code snippets plugin, never in the parent theme, because a theme update overwrites it.