Static and Dynamic Blocks

The editor keeps the blocks of a post in memory as a tree of objects (name, attributes, inner blocks). On save it serializes the tree into the post_content column as HTML wrapped in block delimiters, the HTML comments that start with wp:. On a front-end request, do_blocks() (hooked to the_content, and run by block themes on templates) parses that text back into blocks and renders each one. What happens next depends on the block type:

Two consequences follow from the diagram. The HTML of a static block is frozen at save time, so data that changes later (a new book, a corrected price) is not reflected until someone edits and saves the post again. And because the editor re-runs save() when it opens the post and compares the result with what is stored, changing a static block’s save() later makes old content look invalid. Dynamic blocks have neither problem, at the cost of PHP work on every request.

The three blocks live in the lumen-catalog plugin under src/blocks/, are built to build/blocks/ by the plugin’s build script, wp-scripts build --source-path=src/blocks --output-path=build/blocks --blocks-manifest --experimental-modules (@wordpress/scripts pinned to 37.0.0), and are registered from Lumen\Catalog\Blocks::boot() with wp_register_block_types_from_metadata_collection() (6.8). All use apiVersion 3 and the lumen-catalog category; their block.json fields are explained in block.json and Registration. book-card/ holds block.json, index.js, edit.js, save.js and two stylesheets; latest-books/ and series-shelf/ hold at least block.json, index.js and render.php. After the build, WP_Block_Type::is_dynamic(), which is true when a block type has a render callback, returns false for lumen/book-card and true for the other two (checked with wp eval against the registry).

registerBlockType() attaches two functions to the metadata that block.json describes:

setAttributes() takes an object with the attributes to change; since WordPress 6.9 it also accepts an updater function, setAttributes( ( current ) => ( { count: current.count + 1 } ) ), which must be pure. Attributes are immutable: build a new array or object instead of changing the current one in place.

With the card inserted, the title typed, the ISBN filled in the sidebar and one paragraph added inside it, the editor saves this to post_content (produced by serialize() from @wordpress/blocks with the built block, and stored with wp post create):

Source: Block Editor Handbook: Markup representation of a block

The delimiter’s JSON holds only the attributes that are not sourced from the HTML and differ from their defaults: isbn is there, showIsbn (default true) is not, and title and coverUrl are read back from the <h3> and the src of the <img>. The inner paragraph is a complete block of its own, nested inside the card’s HTML where InnerBlocks.Content placed it. On the server, parse_blocks() shows the same structure:

Source: Code Reference: parse_blocks()

The server does not know the sourced attributes: PHP parses only the JSON in the delimiter, so title exists only in the HTML. A dynamic block that needs a value in PHP must store it in the delimiter (an attribute without source).

When the editor opens a post, it parses every block, rebuilds the attributes (from the delimiter and the sources), calls the block’s current save() with them and compares the result with the stored HTML. The comparison is semantic, not byte for byte: whitespace between tags, the order of HTML attributes and of class names, and self-closing syntax do not matter. A different tag, an extra or missing HTML attribute, or different text does.

To see it fail, the card’s title was changed from <h3> to <h2> in save.js (and in edit.js), the plugin was rebuilt, and the post above was parsed with the new build. The validator reports:

Source: Block Editor Handbook: Edit and Save, Validation

Inner blocks are left out of the comparison (they are validated on their own), which is why the paragraph does not appear in either version. The same messages appear in the browser console as Block validation: … warnings; the last line is the summary of the parser’s isValid flag. Two more changes were tried against the original build: adding a data-x="1" attribute to the stored <article> made the block invalid ("Expected attributes"), and editing the ISBN in the HTML without changing the delimiter made it invalid ("Expected text"), because save() rebuilds the paragraph from the delimiter’s isbn. Swapping the order of the <img> attributes and adding whitespace left it valid.

In the editor, an invalid block shows "Block contains unexpected or invalid content." with an Attempt Block Recovery button, which re-creates the block from its parsed attributes (dropping anything save does not produce). The block’s options menu adds Resolve (a side-by-side comparison offering Convert to HTML or Convert to Blocks) and Convert to Classic Block. Authors should never have to do this after a plugin update.

The fix for an intentional markup change is a deprecated entry that keeps the old save (and the old attributes and supports) so the editor can recognize old content and migrate it. With the original save kept as save-v1.js:

Source: Block Editor Handbook: Deprecation

Parsed with this build, the same post gives Updated Block: lumen/book-card and lumen/book-card: valid: the editor matched the old save, kept the attributes and will write the <h2> version on the next save. Until each post is re-saved, the front end keeps printing the old <h3>, because nothing re-renders static HTML on the server. Ordering, migrate, isEligible and multiple deprecations are covered in Variations, Styles, Transforms and Deprecations.

Validation applies only to blocks that save HTML. A dynamic block saves an empty body (or only its inner blocks) and cannot fail it, whatever render.php outputs.

A block becomes dynamic when its type has a render callback. There are two ways to give it one:

Both receive the same three values:

Source: Block Editor Handbook: Static or Dynamic rendering of a block

A dynamic block can still contain blocks that the author edits. Their markup must be saved, because PHP cannot rebuild what the author typed, so the block’s save returns <InnerBlocks.Content /> and nothing else; render.php then wraps $content (the rendered inner blocks) and adds the server-generated part. lumen/series-shelf lets the editor write a heading and an introduction, and lists the books of one lp_series term below them. Its block.json declares one attribute, series (string, default ""), the supports html: false, align: [ "wide" ] and color, and "render": "file:./render.php". index.js:

Source: Block Editor Handbook: Nested Blocks: Using InnerBlocks

render.php prints the wrapper, $content and the list:

Source: Block Editor Handbook: Metadata in block.json, Render

$content is printed without escaping because it is the output of the inner blocks' own rendering, already filtered when the post was saved; escaping it would print the HTML as text. The stored markup has no wrapper of its own, only the inner blocks between the delimiters:

Source: Block Editor Handbook: Markup representation of a block

and is served as (blank lines removed):

Source: Code Reference: WP_Block

The paragraph is stored as a bare <p> and served with class="wp-block-paragraph": since WordPress 7.0 a render_block_core/paragraph filter adds the class at render time with WP_HTML_Tag_Processor, an example of server-side processing that also applies to static HTML. A useful side effect of saving the inner blocks shows when the plugin is deactivated. the_content of the same page then prints the book card’s stored HTML unchanged, prints nothing for lumen/latest-books, and prints the series heading and introduction without the wrapper and the list: content the author wrote survives, server-generated content disappears. The handbook makes the same point for save in general: in a dynamic block it may return a fallback copy that is shown only if the plugin is ever disabled.

WP_Block::render() passes every block, static or dynamic, through the render_block and render_block_{$name} filters; core uses them for server-side block supports (layout classes, the wp-block-paragraph class), Block Bindings and Block Hooks, and the_content adds more (wp_filter_content_tags() put the decoding="async" on the card’s <img>). A plugin can use the same filters and WP_HTML_Tag_Processor to adjust a static block’s output without touching the stored markup or causing validation errors, but not to replace a dynamic block when content depends on data.

Source: Code Reference: render_block

Source: Block Editor Handbook: Static or Dynamic rendering of a block

A reasonable default: static for content the author writes, dynamic for anything derived from other data (lists, counts, the current user or date) or whose markup is likely to change across releases, hybrid when both are needed. Blocks that also need front-end interactivity stay server-rendered and add the Interactivity API.

Source: Block Editor Handbook: Edit and Save

Attributes come from post_content, which any user who can edit the post can write by hand in the Code editor or send through the REST API, so a render callback treats them as untrusted input: cast integers and clamp them (count is limited to 1–12 above, so a crafted value cannot request thousands of posts), pass slugs through sanitize_key(), and escape every value at output with esc_html(), esc_url() or esc_attr(). A query in a render callback must not leak content the visitor may not see: both Lumen queries ask for post_status publish explicitly, and any other status needs a capability check for the current user. Only get_block_wrapper_attributes() (already escaped) and $content (rendered block HTML) are printed unescaped. On the static side, save() output goes through React’s escaping unless RawHTML is used, and KSES filters the stored HTML for users without unfiltered_html. More in Security for Developers.

The three older books (WordPress All-in-One For Dummies, Pro WordPress, Ultimate WordPress Handbook) do not cover block development: Pro WordPress builds dynamic content as shortcodes and widgets, and the other two use blocks only as authors. Tutorials from the WordPress 5.x years are where outdated block code usually comes from:

Source: Block Editor Handbook: API Versions

The full list across the section is in Where Older Books and Tutorials Are Outdated.