Add new block development "Quick Start Guide" and update the create-block-tutorial-template
#56056
Conversation
ndiego
requested review from
gziolo,
ryanwelcher,
ajitbohra,
juanmaguitar and
fabiankaegy
as code owners
|
Size Change: -251 B (0%) Total Size: 1.7 MB
ℹ️ View Unchanged
|
packages/create-block-tutorial-template/plugin-templates/$slug.php.mustache
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Excellent work with updating the template for the tutorial that’s now wired with the quick start guide.
I left a few notes, but non of them are blocking after you addressed my previous comments. Thank you so much for going through all my feedback with such a care, and changing the plan accordingly.
I very much appreciate it as it makes me happy to help with future iterations whenever you need my input.
packages/create-block-tutorial-template/block-templates/index.js.mustache
Show resolved
Hide resolved
| $block_content = '<p ' . get_block_wrapper_attributes() . '>© ' . esc_html( $display_date ) . '</p>'; | ||
| } | ||
|
|
||
| echo wp_kses_post( $block_content ); |
There was a problem hiding this comment.
I see that the same wp_kses_post is used with many core blocks in certain scenarios. What's the reasoning behind using it at this level? I'm asking because in the case where we render the content as saved to the database then it doesn't differ much from not having the render at all. In effect, I expect that the similar processing would happen somewhere else.
I'm mostly trying to understand how it all really works in WordPress core today so it's clear for me when to use kses.
There was a problem hiding this comment.
It's always been a best practice to late escape anything that is being output to the browser that could be modified by a hook, filter, etc - https://developer.wordpress.org/apis/security/escaping/#toc_3
There was a problem hiding this comment.
If that would be an issue, then all core blocks would call wp_kses_post. However, it isn't the case. If this function is used, it's used to escape the content that comes from the user input when it is expected it might contain HTML. In the case of this block, it should be enough to cast the startingYear to the number and the rest should be safe.
|
Flaky tests detected in 8b0700d. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/6851632645
|
ndiego
deleted the
add/quick-start-guide-and-update-tutorial-template
branch
…block-tutorial-template` (#56056) * Add the new quick start guide. * Update the create-block tutorial template to work with the new quick start guide. * Remove the quick start guide from the create block tutorial. * Add back ABSPATH check. * Revert change to package version number. * Update readme. * Remove @wordpress/icons dependency and add custom icon. * Fix title in manifest. * Fix heading in Quick Start Guide.
|
I did some testing with the quick start guide, and I wanted to share my notes. Overall, the block works as expected and the project is nicely documented. There are tiny details that might get improved. There is no preview: 
One line in "example": {},
Oh, I see that You can provide any content as the starting year: 
Maybe I'm not entirely sure about HTML escaping here as it might be correct, but it would be nice to double-check: 
For what it's worth, in other places, it's placed unescaped, so it seems to be intentional. There is 
It might be good when someone plans to add CSS files, but it might as well be confusing. Maybe we could improve the core of There is one issue reported by JS linter about the missing React dependency. The quick fix would be importing The last part is the simulation of what happens when you open the editor with saved Copyright Date Block after New Year: Screen.Recording.2023-11-24.at.10.44.46.movAs you can see, when you switch from code editor or when you refresh the page then the |
Yeah, I wonder if this is an issue with
This looks to be caused by the
The
Good catch. It's added by default by
It's definitely a quirk, but I think it provides an interesting learning opportunity that will be covered in the tutorial. The "issue" does a nice job illustrating what's going on in the Editor behind the scenes. @juanmaguitar is also working on a separate doc about the Lifecycle of a block, which will be linked to from the tutorial. |
|
I wasn't aware
I see that for some tokens, we allow |
Alternative to #55876
This PR adds a new doc to the Getting Started section of the Block Editor Handbook that demonstrates how to quickly build a custom block using modern JavaScript using a single
npxcommand. This Quick Start Guide leverages the@wordpress/create-blockpackage and the@wordpress/create-block-tutorial-templatetemplate.For the new Quick Start Guide, the
create-block-tutorial-templateneeds to be updated, so this PR also overhauls the block scaffolded by the template. This new "Copyright Date" block utilizes static and dynamic rendering, block supports, custom attributes, and a custom Settings panel. While still relatively simple, it's a more comprehensive example than the current block in the template. This block will also form the foundation of a new "Create a block tutorial" which will be worked on in a future PR.Finally, the Quick Start section of the existing Create a block tutorial is removed since the template will be updated with this PR and the Quick Start section will no longer be accurate once this PR merges. Also, removing this section does not really detract from the current tutorial while I work on creating the new tutorial later this month.
Why?
The goal is to provide new block developers with a quick, hands-on method of creating a block that utilizes modern JavaScript.
This block should also be practical, something that you could actually envision using on a website. This "Copyright Date" block displays the copyright symbol (©) and the current year, the perfect addition to any website's footer.