WooCommerce Code Reference

Spacing_Preprocessor
in package
implements Context_Aware_Preprocessor

This preprocessor is responsible for setting default spacing values for blocks.

In the early development phase, we are setting only margin-top for blocks that are not first or last in the columns block.

Interfaces, Classes and Traits

Context_Aware_Preprocessor
Optional interface for preprocessors that need rendering context.

Table of Contents

CONTAINER_BLOCKS  = array('core/group', 'core/post-content')
Container block names that delegate root padding to their children instead of receiving it themselves.
$post_content_block_names  : array<string|int, mixed>|null
Cached post-content block names to avoid repeated apply_filters calls.
preprocess()  : array<string|int, mixed>
Preprocesses the parsed blocks.
preprocess_with_context()  : array<string|int, mixed>
Preprocesses the parsed blocks with rendering context.
add_block_gaps()  : array<string|int, mixed>
Adds spacing to blocks: margin-top for vertical gaps, horizontal padding for column gaps, and root padding for children of root-level containers.
contains_post_content()  : bool
Checks whether a block contains a core/post-content descendant.
get_block_horizontal_padding()  : array<string|int, mixed>
Extract and validate horizontal padding from a block's style attributes.
get_columns_block_gap()  : string|null
Extracts the horizontal blockGap from a columns block.
get_post_content_block_names()  : array<string|int, string>
Returns the list of block names treated as "post content" for padding delegation.
get_root_padding()  : array<string|int, mixed>
Extracts and sanitizes root horizontal padding from theme styles.
has_explicit_horizontal_padding()  : bool
Checks whether a block explicitly defines any horizontal padding.
has_zero_horizontal_padding()  : bool
Checks whether a block explicitly sets zero horizontal padding.
is_zero_value()  : bool
Checks whether a CSS value is explicitly zero.

Constants

Properties

Methods

preprocess()

Preprocesses the parsed blocks.

public preprocess(array<string|int, mixed> $parsed_blocks, array<string|int, mixed> $layout, array<string|int, mixed> $styles) : array<string|int, mixed>
Parameters
$parsed_blocks : array<string|int, mixed>

Parsed blocks.

$layout : array<string|int, mixed>

Layout.

$styles : array<string|int, mixed>

Styles.

Return values
array<string|int, mixed> —

preprocess_with_context()

Preprocesses the parsed blocks with rendering context.

public preprocess_with_context(array<string|int, mixed> $parsed_blocks, array<string|int, mixed> $layout, array<string|int, mixed> $styles[, Rendering_Context|null $rendering_context = null ]) : array<string|int, mixed>
Parameters
$parsed_blocks : array<string|int, mixed>

Parsed blocks.

$layout : array<string|int, mixed>

Layout.

$styles : array<string|int, mixed>

Styles.

$rendering_context : Rendering_Context|null = null

Rendering context.

Return values
array<string|int, mixed> —

add_block_gaps()

Adds spacing to blocks: margin-top for vertical gaps, horizontal padding for column gaps, and root padding for children of root-level containers.

private add_block_gaps(array<string|int, mixed> $parsed_blocks[, string $gap = '' ][, array<string|int, mixed>|null $parent_block = null ][, array<string|int, mixed> $root_padding = array() ][, bool $apply_root_padding = false ][, array<string|int, mixed> $container_padding = array() ][, array<string|int, mixed> $variables_map = array() ][, string $gap_padding_side = 'padding-left' ]) : array<string|int, mixed>

Root padding is distributed from the outer email wrapper to individual block wrappers. Plain root-level containers (groups without post-content) delegate padding to their children instead of taking it themselves, so alignfull children can skip root padding and span the full email width.

A container that wraps post-content and has its own horizontal padding is a self-contained box: it takes the root padding as an inset itself, and its own padding is suppressed on the box and distributed to descendants as container padding (via a suppress-horizontal-padding flag). This lets full-width children break out of the box, and keeps the two paddings nesting (e.g. 30px outer + 24px own) instead of stacking on every block.

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

Parsed blocks.

$gap : string = ''

Gap.

$parent_block : array<string|int, mixed>|null = null

Parent block.

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

Root horizontal padding with 'left' and 'right' keys.

$apply_root_padding : bool = false

Whether this block should receive root padding (delegated by parent container).

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

Container horizontal padding with 'left' and 'right' keys.

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

Map of CSS variable names to resolved values for preset resolution.

$gap_padding_side : string = 'padding-left'

Physical padding side for generated column gaps.

Return values
array<string|int, mixed> —

contains_post_content()

Checks whether a block contains a core/post-content descendant.

private contains_post_content(array<string|int, mixed> $block) : bool

Searches recursively through container blocks (groups) so that deeply nested template structures like group → group → post-content are handled correctly.

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

The block to check.

Return values
bool — True if the block has a post-content descendant.

get_block_horizontal_padding()

Extract and validate horizontal padding from a block's style attributes.

private get_block_horizontal_padding(array<string|int, mixed> $block[, array<string|int, mixed> $variables_map = array() ]) : array<string|int, mixed>

Preset variable references (e.g. "var:preset|spacing|20") are resolved to their pixel values using the variables map when provided.

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

The block to extract padding from.

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

Map of CSS variable names to resolved values.

Return values
array<string|int, mixed> — Padding with 'left' and 'right' keys, or empty array if invalid/absent.

get_columns_block_gap()

Extracts the horizontal blockGap from a columns block.

private get_columns_block_gap(array<string|int, mixed> $columns_block) : string|null

Only an explicitly defined horizontal gap (blockGap.left) is honored; we do not fall back to the global block spacing, which is vertical-only in the editor and would otherwise add a gap that widens the rendered email.

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

The columns block.

Return values
string|null — The horizontal gap value (e.g., "30px" or "var:preset|spacing|30") or null if not explicitly set.

has_explicit_horizontal_padding()

Checks whether a block explicitly defines any horizontal padding.

private has_explicit_horizontal_padding(array<string|int, mixed> $block) : bool

Containers with explicit padding (any value) manage their own layout and should stop delegating root padding to their children.

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

The block to check.

Return values
bool — True if the block defines horizontal padding.

has_zero_horizontal_padding()

Checks whether a block explicitly sets zero horizontal padding.

private has_zero_horizontal_padding(array<string|int, mixed> $block) : bool

Explicit zero padding (0, 0px, 0em, etc.) signals that the block intentionally wants edge-to-edge layout. Root padding should not be added on top.

Non-zero padding (e.g. 20px) is internal content spacing and does not affect root padding — both can coexist independently.

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

The block to check.

Return values
bool — True if the block explicitly sets zero horizontal padding.