WooCommerce Code Reference

Gallery extends Abstract_Block_Renderer
in package

Gallery block renderer.

This renderer handles core/gallery blocks with proper email-friendly HTML layout.

Table of Contents

$current_rendering_context  : Rendering_Context|null
Rendering context for calls using the legacy add_spacer() signature.
render()  : string
Render the block.
add_spacer()  : string
Add a spacer around the block for vertical spacing (margin-top).
add_spacer_with_context()  : string
Add a spacer around the block with rendering context.
compile_css()  : string
Compile objects containing CSS properties to a string.
get_inner_content()  : string
Extract inner content from a wrapper element.
get_styles_from_block()  : array<string|int, mixed>
Wrapper for wp_style_engine_get_styles which ensures all values are returned.
render_content()  : string
Renders the gallery block content using a table-based layout.
apply_aspect_ratio_crop()  : string
Apply an aspect-ratio crop to a sanitized <img> tag.
build_email_layout()  : string
Build the email-friendly layout for gallery blocks.
build_gallery_row_table()  : string
Build a single gallery row as a separate table (following tiled gallery pattern).
build_gallery_table()  : string
Build the gallery table structure with proper rows and cells.
extract_gallery_caption()  : string
Extract gallery-level caption from the original block content.
extract_image_from_html()  : string
Extract and sanitize image with optional link and caption from HTML content.
extract_images_from_gallery_content()  : array<string|int, mixed>
Extract all images from gallery content with their links and captions.
get_cell_width()  : int
Estimate the rendered width (in px) of the gallery cell that holds a given image.
get_columns_from_attributes()  : int
Get the columns value from block attributes.
normalize_image_for_email()  : string
Normalize a gallery <img> for email: drop the web-only class and rein in an oversized raw width.
parse_aspect_ratio()  : float|null
Parse an aspect ratio attribute value (e.g. "1", "1.5", "4/3") into a numeric width/height ratio.
prepare_image_html()  : string
Sanitize a raw gallery <img>, apply the optional aspect-ratio crop, then normalize it for email rendering.

Properties

Methods

add_spacer()

Add a spacer around the block for vertical spacing (margin-top).

protected add_spacer(string $content, array<string|int, mixed> $email_attrs) : string

Horizontal root padding is applied uniformly by Content_Renderer::render_block() so that all blocks — including those using render_email_callback without Abstract_Block_Renderer — receive consistent padding.

Parameters
$content : string

The block content.

$email_attrs : array<string|int, mixed>

The email attributes.

Return values
string —

add_spacer_with_context()

Add a spacer around the block with rendering context.

protected add_spacer_with_context(string $content, array<string|int, mixed> $email_attrs[, Rendering_Context|null $rendering_context = null ]) : string
Parameters
$content : string

The block content.

$email_attrs : array<string|int, mixed>

The email attributes.

$rendering_context : Rendering_Context|null = null

Rendering context.

Return values
string —

get_inner_content()

Extract inner content from a wrapper element.

protected get_inner_content(string $block_content[, string $tag_name = 'div' ]) : string

Removes the outer wrapper element (e.g., div) and returns only the inner HTML content. This is useful when you need to strip the wrapper and use only the inner content.

Parameters
$block_content : string

Block content with wrapper element.

$tag_name : string = 'div'

Tag name of the wrapper element (default: 'div').

Return values
string — Inner content without the wrapper element, or original content if wrapper not found.

get_styles_from_block()

Wrapper for wp_style_engine_get_styles which ensures all values are returned.

protected get_styles_from_block(array<string|int, mixed> $block_styles[, bool $skip_convert_vars = false ]) : array<string|int, mixed>
Parameters
$block_styles : array<string|int, mixed>

Array of block styles.

$skip_convert_vars : bool = false

If true, --wp_preset--spacing--x type values will be left in the original var:preset:spacing:x format.

Return values
array<string|int, mixed> —

apply_aspect_ratio_crop()

Apply an aspect-ratio crop to a sanitized <img> tag.

private apply_aspect_ratio_crop(string $img_html, string|null $aspect_ratio, int $cell_width[, array<string|int, mixed> $image_attrs = array() ]) : string

Email clients can't crop client-side reliably (object-fit/aspect-ratio are unsupported in Gmail), so the only way to truly honor the crop everywhere is to serve an already-cropped image file. This method exposes the {@see 'woocommerce_email_editor_gallery_cropped_image_url'} filter so integrations (e.g. Jetpack/Photon on WordPress.com) can rewrite the image URL to a server-cropped version. When that happens, the image is given concrete width/height dimensions so it renders correctly even in clients without CSS crop support.

When no integration crops the URL (e.g. self-hosted sites with no image CDN), the method falls back to inline aspect-ratio + object-fit: cover CSS. Clients that support it (Apple Mail, iOS Mail, modern webmail) render the crop; the rest fall back to the natural aspect ratio, matching the previous behavior with no regression.

Parameters
$img_html : string

Sanitized HTML.

$aspect_ratio : string|null

Aspect ratio to apply (e.g. "1" or "4/3").

$cell_width : int

Estimated display width of the gallery cell in px.

$image_attrs : array<string|int, mixed> = array()

Parsed attributes of the core/image block (id, sizeSlug, ...).

Return values
string — Image HTML with the crop applied, or the input unchanged when no valid ratio.

build_email_layout()

Build the email-friendly layout for gallery blocks.

private build_email_layout(array<string|int, mixed> $gallery_images, array<string|int, mixed> $parsed_block, string $block_content, Rendering_Context $rendering_context) : string
Parameters
$gallery_images : array<string|int, mixed>

Array of image HTML strings.

$parsed_block : array<string|int, mixed>

Full parsed block data.

$block_content : string

Original block content.

$rendering_context : Rendering_Context

Rendering context.

Return values
string — Rendered HTML.

build_gallery_row_table()

Build a single gallery row as a separate table (following tiled gallery pattern).

private build_gallery_row_table(array<string|int, mixed> $row_images, int $total_columns, int $cell_padding) : string
Parameters
$row_images : array<string|int, mixed>

Images for this row.

$total_columns : int

Total number of columns.

$cell_padding : int

Cell padding.

Return values
string — Row table HTML.

build_gallery_table()

Build the gallery table structure with proper rows and cells.

private build_gallery_table(array<string|int, mixed> $gallery_images, int $columns) : string

Uses the tiled gallery pattern: separate tables for each row, then wrap in main table.

Parameters
$gallery_images : array<string|int, mixed>

Array of image HTML strings.

$columns : int

Number of columns.

Return values
string — Gallery table HTML.

extract_image_from_html()

Extract and sanitize image with optional link and caption from HTML content.

private extract_image_from_html(string $html_content[, string|null $aspect_ratio = null ], int $cell_width[, array<string|int, mixed> $image_attrs = array() ]) : string

This is the unified method that handles all image extraction scenarios.

Parameters
$html_content : string

HTML content containing the image.

$aspect_ratio : string|null = null

Optional aspect ratio (e.g. "1" or "4/3") to crop the image to.

$cell_width : int

Estimated display width of the gallery cell in px.

$image_attrs : array<string|int, mixed> = array()

Parsed attributes of the core/image block (id, sizeSlug, ...).

Return values
string — Sanitized image HTML with proper link and caption handling.

extract_images_from_gallery_content()

Extract all images from gallery content with their links and captions.

private extract_images_from_gallery_content(string $block_content, array<string|int, mixed> $parsed_block, int $columns, int $layout_width) : array<string|int, mixed>
Parameters
$block_content : string

The rendered gallery block HTML.

$parsed_block : array<string|int, mixed>

The parsed block data.

$columns : int

Number of gallery columns.

$layout_width : int

Available layout width in px.

Return values
array<string|int, mixed> — Array of sanitized image HTML strings.

get_cell_width()

Estimate the rendered width (in px) of the gallery cell that holds a given image.

private get_cell_width(int $index, int $image_count, int $columns, int $layout_width) : int

The gallery packs images into rows of $columns. A complete row splits the layout width evenly, but an incomplete final row is distributed across only its remaining images — a lone trailing image spans the full width (see {@see}). Sizing the crop to the actual cell keeps an image CDN from serving an undersized file for such images.

Parameters
$index : int

Zero-based index of the image among the rendered images.

$image_count : int

Total number of rendered images.

$columns : int

Number of gallery columns.

$layout_width : int

Available layout width in px.

Return values
int — Cell width in px (at least 1).

normalize_image_for_email()

Normalize a gallery <img> for email: drop the web-only class and rein in an oversized raw width.

private normalize_image_for_email(string $img_html, int $cell_width) : string

The block editor stores the intrinsic width/height of the original file (e.g. width="2560"). Outlook honors that raw width literally — blowing a thumbnail-sized cell wide open. The core/image renderer avoids this with add_image_dimensions(); the gallery path (which sizes to a per-cell width rather than the block width) needs the equivalent tailored to its cell model. We clamp the width down to the cell it renders in, but only when the stored width exceeds it, scaling any height to keep the aspect ratio. An image with no explicit width is left responsive (no attribute added), and a width already at or below the cell width is untouched — so the concrete dimensions the aspect-ratio crop sets for a server-cropped file, and the deliberately dimensionless CSS-crop fallback, are both preserved.

The other web-only attributes core emits (srcset, sizes, loading, decoding) are already stripped upstream by {@see}, whose allowlist keeps only src/alt/width/height/class/style; the class is the one web-only attribute it preserves, so that is all we remove here (matching the core/image renderer, which also drops it).

Parameters
$img_html : string

Sanitized HTML.

$cell_width : int

Estimated display width of the gallery cell in px.

Return values
string — The normalized HTML.

parse_aspect_ratio()

Parse an aspect ratio attribute value (e.g. "1", "1.5", "4/3") into a numeric width/height ratio.

private parse_aspect_ratio(string $aspect_ratio) : float|null
Parameters
$aspect_ratio : string

Aspect ratio value.

Return values
float|null — The ratio (width divided by height), or null when the value is invalid.

prepare_image_html()

Sanitize a raw gallery <img>, apply the optional aspect-ratio crop, then normalize it for email rendering.

private prepare_image_html(string $raw_img_html, string|null $aspect_ratio, int $cell_width, array<string|int, mixed> $image_attrs) : string

This is the single entry point every extraction path uses so image hardening (dropping the web-only class and reining in an oversized raw width) is applied consistently, whether the image is linked, unlinked, or cropped.

Parameters
$raw_img_html : string

Raw HTML extracted from the block content.

$aspect_ratio : string|null

Optional aspect ratio (e.g. "1" or "4/3") to crop the image to.

$cell_width : int

Estimated display width of the gallery cell in px.

$image_attrs : array<string|int, mixed>

Parsed attributes of the core/image block (id, sizeSlug, ...).

Return values
string — Prepared HTML, or empty string when the image is invalid.