WooCommerce Variation and Gallery Images
External Images does more than swap out the WooCommerce featured image. It also feeds external URLs into the product gallery and into per-variation images, so a whole affiliate or feed-driven catalogue can render from a third party CDN without a single file being downloaded into your media library. This article explains where those URLs are stored, the constants that tune the behaviour, and how to match the plugin to your theme or variation-gallery plugin.
Where the images are stored
Three separate things are set with external URLs: the product’s main image, the product gallery, and each variation’s own image and gallery.
The main image is read from the external_image_url post meta. If you use Datafeedr the plugin also checks merchant_image_url and _dfrps_featured_image_url, in the order external_image_url, merchant_image_url, _dfrps_featured_image_url (the largest merchant image tends to win for Datafeedr users). On first read the URL is normalised into an internal _external_image_url meta that caches the width, height and any matching attachment id, so later page loads do less work.
The gallery is stored in the _ei_wcgallery post meta. Internally this is an array, one entry per image, each holding url, full_url, width, height, alt, title and an attachmentid. You do not have to build that array by hand. If you save _ei_wcgallery (or the editor gallery field) as a plain pipe-separated string of URLs (url1|url2|url3), the plugin explodes it on the | character and expands it into the full array on the next read, measuring each image and writing the result back. The plugin can also lift gallery URLs out of the external_image_url field itself (comma or pipe separated) or out of an eigallery meta field, which is handy when an importer can only populate one column.
You never have to build the _ei_wcgallery array yourself. Save a plain url1|url2|url3 string and the plugin measures each image and expands it into the full array on the next read. That is what lets a bulk importer populate galleries from a single text column.
Variations work the same way, one level down. Each product_variation post carries its own _external_image_url (the variation’s main image) and its own _ei_wcgallery (the variation’s gallery). In the product editor these are saved under ei_variation_wcgallery[<variation_id>][...], so every variation keeps an independent set of external images.
At display time External Images filters woocommerce_product_get_gallery_image_ids and woocommerce_product_variation_get_gallery_image_ids to hand WooCommerce a set of gallery ids derived from _ei_wcgallery, and swaps the real image src at render time through wp_get_attachment_image_src. That is why the images appear in the normal gallery slots even though nothing was downloaded.
The gallery and variation constants
These are defined in defines.php and can be overridden from wp-config.php (each is wrapped in a defined() guard). Defaults confirmed in the code:
| Constant | Default | What it does |
|---|---|---|
EI_ADD_FEATURED_IMAGE_TO_GALLERY | false | Prepends the product’s own main external image to the front of the gallery array, so the featured image also shows as the first gallery slide. |
EI_SHOW_VARIATION_IMAGES_IN_MAIN_GALLERY | false | On a variable (parent) product, appends every child variation’s featured image to the parent’s main gallery, so all variation images appear together before any variation is chosen. |
EI_GRAB_PARENT_GALLERY_IF_NO_GALLERY | false | If an item has no _ei_wcgallery of its own, falls back to the parent post’s gallery meta. Useful when variations should inherit the parent’s gallery. |
EI_DISABLE_VARIATION_JS | not defined (commented out) | Superseded. See the note below – the live control is a settings-page checkbox, not this constant. |
EI_VARIATION_GALLERY_WRAPPER_CSS | .woocommerce-product-gallery | The CSS selector for your theme’s gallery container. It is passed to the front-end JavaScript so the correct element is replaced when a shopper picks a variation. |
Note on EI_DISABLE_VARIATION_JS: in defines.php this define is commented out, so it is not set by default and you should not rely on it. The option was moved onto the settings page as the “Variation Gallery JavaScript” checkbox (ei_settings['disable_variation_js']). When that box is ticked, the front-end show_variation handler returns early and does not AJAX-swap the gallery on variation selection. Flip it on if selecting a variation leaves the gallery unclickable or breaks your theme’s slider, and let the theme handle the swap itself.
Matching your theme or variation-gallery plugin
When a shopper selects a variation, External Images fetches that variation’s images over admin-ajax (ei_get_variation_images) and injects the new main image and thumbnails into the page. It needs to know which element on the page is the gallery, and that is exactly what EI_VARIATION_GALLERY_WRAPPER_CSS provides. Set it to whatever wrapper your theme or variation-gallery plugin renders. The three values baked into defines.php (one active, two shown as commented examples) cover the common cases:
.woocommerce-product-gallery– stock WooCommerce and most standard themes (the default)..woo-variation-product-gallery– the Woo Variation Product Gallery plugin (meta keywoo_variation_gallery_images)..rtwpvg-images– the RT WooCommerce Variation Gallery plugin (meta keyrtwpvg_images).
For those two variation-gallery plugins the plugin also filters their gallery meta (woo_variation_gallery_images and rtwpvg_images) so the external URLs flow into their galleries as well, not just the stock one.
WoodMart has dedicated handling. External Images detects the theme (wp_get_theme()->get_template() equals WoodMart) and, through the woocommerce_available_variation filter, attaches an additional_variation_images array to each variation so WoodMart’s own gallery picks up the external images. It honours WoodMart’s variation_gallery theme option, tags each image class through the woodmart_single_product_gallery_image_class filter, and after injecting the new images the JavaScript calls woodmartThemeModule.productImagesGallery() to reinitialise the slider. If you run WoodMart with a non-standard gallery, keep EI_VARIATION_GALLERY_WRAPPER_CSS pointed at the wrapper WoodMart actually renders.
One more related filter: ei_user_resized_images. When the “resize images” setting is off, the plugin forces this filter to false so external images are served at their native size rather than being passed through the resizer.
Practical guidance
Leave every constant at its default first and check the front end. Each one exists to fix a specific display problem, so only change the one that matches the symptom you actually see. Turning them all on pre-emptively tends to create the odd gallery layout you were trying to avoid.
Start with the defaults. Only reach for the constants when the display is not what you want:
- Featured image missing from the gallery strip: set
EI_ADD_FEATURED_IMAGE_TO_GALLERYto true. - You want every colour/size image visible on the parent product before a selection is made: set
EI_SHOW_VARIATION_IMAGES_IN_MAIN_GALLERYto true. - Variations that should reuse the parent’s gallery show nothing: set
EI_GRAB_PARENT_GALLERY_IF_NO_GALLERYto true. - The gallery goes blank or stops responding after picking a variation: point
EI_VARIATION_GALLERY_WRAPPER_CSSat the right wrapper first, and if the theme should own the swap, tick the “Variation Gallery JavaScript” (disable) setting.
These constants control the automatic, catalogue-wide behaviour. If you would rather set images product by product from the editor (the main image, the gallery, or a single variation’s images), see “Changing external images for WooCommerce products manually”. For the meta keys, filters and hooks referenced above, see “Developer Reference”, and for the real-estate gallery equivalent see “Houzez Theme Gallery Display Options”.
Comments