Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Fundamentals of Block Development - Static or Dynamic rendering of a block #57250

Merged
Merged
Changes from 1 commit
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
155b40b
Static or Dynamic rendering of a block first draft
juanmaguitar Dec 19, 2023
a66d0f4
Add explanation of static and dynamic rendering of blocks
juanmaguitar Dec 20, 2023
c8144e5
Merge branch 'trunk' into fundamentals-block-development/static-dynam…
juanmaguitar Dec 21, 2023
28da078
Updated context with first version
juanmaguitar Dec 21, 2023
1434699
Update link in static-dynamic-rendering.md
juanmaguitar Dec 21, 2023
98587a8
Refactor static/dynamic rendering explanation in static-dynamic-rende…
juanmaguitar Dec 21, 2023
f5e5732
Update static/dynamic rendering explanation
juanmaguitar Dec 22, 2023
3233c88
Update block fundamentals documentation with core blocks examples
juanmaguitar Dec 22, 2023
d830bfc
Refactor dynamic rendering in save function
juanmaguitar Dec 22, 2023
b33923c
Refactor static/dynamic rendering examples in static-dynamic-renderin…
juanmaguitar Dec 22, 2023
dc8d2d8
Update examples of core blocks with static rendering
juanmaguitar Dec 22, 2023
9f629b7
Update InnerBlocks link in static-dynamic-rendering.md
juanmaguitar Dec 22, 2023
5a6dd25
Update docs/getting-started/fundamentals/README.md
juanmaguitar Jan 4, 2024
b9e9bc2
Update docs/getting-started/fundamentals/markup-representation-block.md
juanmaguitar Jan 4, 2024
798df76
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
c9d2068
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
5885922
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
e6f973a
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
62407bf
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
bcddeb8
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
af1577c
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
add1bba
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
39ece62
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
9fb116a
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
9f45386
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
538f438
Update docs/getting-started/fundamentals/static-dynamic-rendering.md
juanmaguitar Jan 4, 2024
6df94bc
Merge branch 'trunk' into fundamentals-block-development/static-dynam…
juanmaguitar Jan 4, 2024
d26ed17
Merge branch 'fundamentals-block-development/static-dynamic-rendering…
juanmaguitar Jan 4, 2024
d93db3c
Update diagrams and improved examples
juanmaguitar Jan 5, 2024
5995411
Updates on the text as per Justin's feedback
juanmaguitar Jan 7, 2024
1c8bd48
small adjustments
juanmaguitar Jan 7, 2024
879b3ca
Fix capitalization in static-dynamic-rendering.md
juanmaguitar Jan 8, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/getting-started/fundamentals/static-dynamic-rendering.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Static or Dynamic rendering of a block
juanmaguitar marked this conversation as resolved.
Show resolved Hide resolved



A block can define dynamic rendering can be defined in two ways:
- The `register_block_type()` function includes a `render_callback` argument.
- A `render` property is added to `block.json`, whose value points to a separate PHP file (usually named `render.php`).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like this is very confusing. This explains how to use dynamic rendering without explaining first what dynamic rendering even is / letting the reader know that there are two different kinds of rendering


Blocks can have static or dynamic rendering:
- If no dynamic rendering has been been defined the rendering

## Blocks with Static Rendering

Blocks with static rendering **generate the HMTL for the frontend at "update-time" (when it's saved)**:
- Blocks with static render use their markup representation in the DB to return the markup used in the frontend for the block
- The `save()` function writes the block’s markup inside the block indicators (HTML comments).
- Only the markup inside the block indicators is returned as markup to be rendered for the block in the frontend.
- For blocks with static render, the markup returned to the frontend is defined/set when the page is saved.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically this is not entirely correct. Yes static blocks save their markup to the database and return said markup on the frontend. However both core and extenders can and do modify that markup before it gets rendered on the frontend via the render_callback or render_block hook.

An example of this is the core cover block which is a static block that does some PHP magic if the "use featured image" setting to dynamically inject the featured image.

Same with the Image block. Yes it saves markup to the DB. But when the image is served through the media library the sourceset generation etc is done on the server.

The List block is a static block that dynamically gets it's wrapping class name (wp-block-list) injected into the blocks markup on the server.


My point here is not that this should all be documented here. Instead I worry that the current explanation makes one feel too "safe" that the markup generated in the save function in JS is output 100% as is without modification. Which is not true.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My point here is not that this should all be documented here. Instead I worry that the current explanation makes one feel too "safe" that the markup generated in the save function in JS is output 100% as is without modification. Which is not true.

Thanks for this explanation. Based on your explanations I agree the current text may be misleading.
I'll work on a different text proposal to take these cases into account.

## Blocks with Dynamic Rendering

Blocks with dynamic rendering **generate the HMTL for the frontend at "request-time" (when it's requested)**
- These blocks usually need to display info that is not known at the time the page is saved
- Dynamic rendering for a block can be defined:
- The `register_block_type()` function includes a `render_callback` argument.
- A `render` property is added to `block.json`, whose value points to a separate PHP file (usually named `render.php`).
- Dynamic render methods receive attribute, inner content information and additional required dynamic site information.
Loading