diff --git a/docs/getting-started/fundamentals/README.md b/docs/getting-started/fundamentals/README.md index 42dbace9d7ba3f..70f76c98c8ecf7 100644 --- a/docs/getting-started/fundamentals/README.md +++ b/docs/getting-started/fundamentals/README.md @@ -10,3 +10,4 @@ This section provides an introduction to the most relevant concepts in block dev 1. **[Markup representation of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block):** How blocks are represented in the database, theme templates, and patterns. 1. **[Static or Dynamic rendering of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering):** How blocks generate their front-end output either dynamically or statically. 1. **[JavaScript in the Block Editor](https://developer.wordpress.org/block-editor/getting-started/fundamentals/javascript-in-the-block-editor):** How to work with modern JavaScript when developing for the Block Editor. +1. **[Lifecycle of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/lifecycle-of-block):** Understanding the different phases a block goes through and its various format transformations during its lifecycle. diff --git a/docs/getting-started/fundamentals/lifecycle-of-block.md b/docs/getting-started/fundamentals/lifecycle-of-block.md new file mode 100644 index 00000000000000..e768b0e6fa7648 --- /dev/null +++ b/docs/getting-started/fundamentals/lifecycle-of-block.md @@ -0,0 +1,172 @@ +# Lifecycle of a block + +A WordPress block goes through several distinct phases during its lifecycle, from registration to rendering. Understanding these phases is crucial for block development. + +## Overview of block lifecycle phases + +1. Registration phase +2. Edit phase (Block Editor) +3. Save phase +4. Serialization phase +5. Rendering phase + +### 1. Registration phase + +When WordPress loads, blocks go through a registration process: + +```js +// Client-side registration +registerBlockType('namespace/block-name', { + // Block configuration +}); + +// Server-side registration +register_block_type('namespace/block-name', array( + // Block configuration +)); +``` + +During registration: +- Block metadata from `block.json` is loaded +- Block assets are enqueued +- Server-side and client-side handlers are registered +- Block variations and styles are registered + +### 2. Edit phase + +The edit phase occurs within the Block Editor when users interact with the block: + +- Block is instantiated as a React component +- Block attributes are initialized with default or saved values +- Edit function renders the block's interface +- Block controls and inspector panels become available +- Changes are stored in the block's attributes + +*Example: Block edit lifecycle* +```js +edit: ({ attributes, setAttributes, isSelected }) => { + // Component mount + useEffect(() => { + // Initialize block + }, []); + + // User interactions + const onChangeContent = (newContent) => { + setAttributes({ content: newContent }); + }; + + // Render block interface + return ( +
+ {/* Block content and controls */} +
+ ); +} +``` + +### 3. Save phase + +The save phase occurs when the post is saved: + +- Block's save function is called +- Current attributes are used to generate block markup +- For dynamic blocks (`save: null`), only the block comment is saved + +*Example: Block save function* +```js +save: ({ attributes }) => { + return ( +
+ {/* Static markup generated from attributes */} +
+ ); +} +``` + +### 4. Serialization phase + +During serialization, blocks are converted to their HTML storage format: + +```html + +
+ Block content +
+ +``` + +Key aspects of serialization: +- Attributes are stored as JSON in the block comment +- Block markup is validated against the save function output +- Changes in markup structure require block deprecation handling + +### 5. Rendering phase + +The final phase where blocks are displayed on the frontend: + +For static blocks: +- Saved markup is retrieved from the database +- Markup is filtered through `render_block` filters +- Final HTML is output to the page + +For dynamic blocks: +- Block attributes are passed to the render callback +- Server-side function generates fresh markup +- Generated HTML is filtered and displayed + +*Example: Dynamic block render callback* +```php +function render_callback($attributes, $content) { + $wrapper_attributes = get_block_wrapper_attributes(); + + return sprintf( + '
%2$s
', + $wrapper_attributes, + esc_html($attributes['content']) + ); +} +``` + +## Block format transformations + +Throughout its lifecycle, a block exists in different formats: + +1. **JavaScript object format** + - Used during registration and in the editor + - Contains all block configuration and attributes + +2. **React component format** + - Active in the Block Editor + - Handles user interactions and UI rendering + +3. **HTML comment format** + - Storage format in the database + - Contains block name and attributes + +4. **HTML markup format** + - Final rendered output + - Either stored (static) or generated (dynamic) + +## Best practices + +1. **Validation** + - Always validate data during format transformations + - Handle deprecated block versions gracefully + - Implement proper error handling + +2. **Performance** + - Minimize unnecessary re-renders in the edit function + - Use memoization for expensive computations + - Implement proper cleanup in useEffect hooks + +3. **Compatibility** + - Test block migrations thoroughly + - Maintain backward compatibility + - Follow WordPress coding standards + +## Additional Resources + +- [Block API Reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/) +- [Data Flow in the Block Editor](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/) +- [Block Deprecation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) +- [Block Validation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) diff --git a/docs/manifest.json b/docs/manifest.json index 8f267e79ef4feb..4efa8a4f011529 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -107,6 +107,12 @@ "markdown_source": "../docs/getting-started/fundamentals/javascript-in-the-block-editor.md", "parent": "fundamentals" }, + { + "title": "Lifecycle of a block", + "slug": "lifecycle-of-block", + "markdown_source": "../docs/getting-started/fundamentals/lifecycle-of-block.md", + "parent": "fundamentals" + }, { "title": "Glossary", "slug": "glossary", diff --git a/docs/toc.json b/docs/toc.json index 69fe86a08256b6..b2f69cdd83edb5 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -47,6 +47,9 @@ }, { "docs/getting-started/fundamentals/javascript-in-the-block-editor.md": [] + }, + { + "docs/getting-started/fundamentals/lifecycle-of-block.md": [] } ] },