Course: Block Development #771
Comments
|
Michael Burridge is working on this course and I will be supporting him along the way as Instructional Designer. Here is the initial planning doc: Block Development Course Objectives |
|
Thanks Wes. |
Hi, @westnz that link requires access. Can we make it read-only for public view? |
|
Thank you @azhiya Michael changed the access to read-only for public view. |
|
Discussed in Slack: https://wordpress.slack.com/archives/C02RW657Q/p1654255617979579 |
|
COURSE UPDATE Michael has started building the course in Sensei: The outline is complete and he has drafted the Introduction and Module 1. Herewith my feedback so far and recent discussions we have had: Feedback – Introduction & Getting started module - Wes Introduction What is a block? I would also suggest using the following blocks to highlight/summarize/emphasize certain points or concepts going forward: Info Callout, Tip Callout and Alert Callout. I noticed you have used the Tip Callout in the Build and run a project lesson. 😃 Set up your development environment <should we give instructions for this? Docker is needed.> Yes, I think so You mentioned; “Additionally you should know, or be prepared to learn, the basics of React.” Could you add links to more resources for those who are not well-acquainted with React? Scaffold your first block I want to pause here and think about how we can engage learners throughout the course by using some techniques like using visuals, storytelling, examples of before and after, compelling dilemmas or asking interesting questions. Understand the structure of the project The video that we will be creating will be helpful here to go through the src directory. Adding too many images here will lead to cognitive overload. Build and run your project Make some simple changes Michael's response: Hey Wes, thanks so much for casting an eye over the course as it exists thus far, and for your in-depth comments. Introduction My only suggestion is to use some bullet points when you mention “So, what will you be building in this course?” TBH I think I’d prefer the introduction to have a more conversational flow and a more engaging style. What is a block? I think we need to look at how to add visually appealing features I would also suggest using the following blocks to highlight/summarize/emphasize certain points or concepts going forward I agree with these points, I’ll revisit this (and probably many other lessons) later on when I’ve got the bulk of the content done to add refinements such as the ones you suggest here. For now I want to get a first draft done that can be revised and iterated on. Set up your development environment Could you add links to more resources for those who are not well-acquainted with React? Done! Regarding my questions, which you answered in the affirmative, my doubts are about overloading the learner with peripheral information that can be obtained elsewhere. Should we go for “completeness” or keep things tightly focussed on the subject matter we’re addressing? Scaffold your first block I want to pause here and think about how we can engage learners throughout the course by using some techniques like using visuals, storytelling, examples of before and after, compelling dilemmas or asking interesting questions. Great points. Again something that can be addressed when I come to revise the content. For now I’m going to focus on getting as much content in as possible. Understand the structure of the project Maybe we could use a Tip Callout to highlight the directories that will probably never be touched. Good idea. I’ll bear in mind ways in which I can make the content more visually appealing and more easily digestible once I’ve got the first draft down. For now I’ve changed it to use bullet points just to break up the “monolithic block of text” look. Make some simple changes Yup. 😄 Thanks again for giving it the once over Wes, and thanks too for your kind remarks. I’ll bear all your points in mind as I work on future lessons. I guess I’m more or less on the right track so for now I’ll just keep on keeping on. Wes's feedback: Absolutely! You are more than on the right track and it makes a lot of sense coming back to add refinements etc. my doubts are about overloading the learner with peripheral information that can be obtained elsewhere. Should we go for “completeness” or keep things tightly focussed on the subject matter we’re addressing? Good point. Maybe you could just add the info as a footer at the end of the lesson if you wish to. Something like this: |
|
Update: Michael has now added content to module 2. He hopes to have the text-based part of the course finished by the end of August. 🤞 |
|
Update: work done in the past two weeks (08 Aug 2022 - 19 Aug 2022) I encountered a couple of minor bugs in the project as I reconstructed the project for the purposes of creating the course. They were mainly me making coding errors, but they still took a bit of time to track down. The target for this period was to finish the four lessons that would complete the course up to the end of module 4. The course structure is continually being modified as the content develops and two new lessons were added. I therefore haven’t completed up to the end of module 4 as planned, so the target was not met in that sense, but I did complete four lessons. The lesson "Conditionally display controls" has been moved to later in the course. Achievements in this period
|
|
Thank you @mburridge. You sure have put a lot of work into this so far! Well done!! |
|
The draft of the Block Development Course is now ready for review. 🎉 Please provide your feedback as a comment here by Thursday, 15 September. Here's some things to take into account during your review of the course:
Thanks. I'm looking forward to your comments and feedback. |
|
Excellent work @mburridge. I started looking at the course to check how it all fits together and it's an impressive work. I like how you divided it into sections and how you introduce new concepts as the work in the block progresses. I have some technical feedback to share for the first two modules: General note, code examples don't follow WordPress Coding Standards. I'm not sure if that is something that is important here or not, but it's noticeable for someone who is forced to follow them on the daily basis. What is a block?
Technically speaking the block editor is the default WordPress editor from WordPress 5.0 (December 2018). Initially, the editor used TinyMCE internally and it was refactored later in the development process. I wouldn't highlight it being strictly a replacement for TinyMCE. It's far more important to emphasize instead the concept of blocks and how it lets users edit every aspect of the WordPress site using a single interface. It isn't posts and pages anymore. Scaffold your first block
Side note here. If you don't provide a name of the plugin/block then Create Block will prompt questions on the terminal and the user is able to customize many things. In effect, instead of manually editing Understand the structure of the project
It isn't only a post or page, it's all post types, including templates used by a block theme. Add ‘Block Supports’ controlsI have mixed feelings when seeing experimental APIs like "__experimentalDefaultControls" in the official educational materials. In general, this is something that is meant to be used only in the Gutenberg plugin. See the recent post on that topic: https://make.wordpress.org/core/2022/08/10/proposal-stop-merging-experimental-apis-from-gutenberg-to-wordpress-core/. It would be great to figure out how to make this API stable in the upcoming WordPress 6.1 release so everyone could freely use the stable version without this experimental prefix. Define default settings in block.json
While this is a great hint, it might feel very confusing for someone who is exposed for the first time to learning about building blocks for WordPress. In the ideal world, we would present how to use only stable APIs so people don't need to learn about all those nuances. |
|
Module 3, 4 & 5 Create custom inspector panel controlsIt's a bit painful experience to avoid using Add more configuration optionsI have a similar concern as in the earlier module about using the experimental API that isn't considered ready for production use: Work with the InnerBlocks componentThis is my favorite part when inner blocks get introduced ❤️ 🎉 Refining the projectThat's really nice to present all the opportunities to simplify the code 💯 Add style variationsI like the idea of showing how to use style variations. There is a drop cap native support in the block editor. It works with Paragraph blocks out of the box. You can look for The finished projectI don't see any experimental APIs included on this page. This is great, I'm wondering why there is a disconnect with the previous modules. |
|
Thanks so much for reviewing the course @gziolo and for your comments and feedback. Thanks also for your very kind remarks.
The repo for the project is here. Please feel free to submit PRs that bring the code into line with the WordPress Coding Standards (if you have the time) where you discern that it deviates from them and I'll update the tutorial accordingly.
Good point. The earlier parts of the course are the ones most in need of revision I think, so I'll factor that in when I come to review and revise the course.
Ideally I'd like to keep the course tightly focused around the project being built and not have too many side avenues to distract the learner. @jonathanbossenger has created a separate tutorial on Create Block which I reference in that lesson. Do you feel that it's important to explain the scope of the tool at that stage of the tutorial?
Another good point, I'll take it into account when reviewing and revising.
I agree and have similar misgivings, and as you say this is confusing for the user. I've rewritten the following two lessons to remove all reference to "__experimentalDefaultControls": Thanks once again for your review. I see you've just posted another comment above 😄 - I'll address that separately. |
In theory, you should be able to run the following commands with npm run format
npm run lint:css
npm run lint:jsIt probably gets the default version of Prettier installed instead of the forked one for WordPress. I guess it's the issue with npm aliases... Yes, I checked "prettier": {
"version": "2.6.2",
"resolved": "https://registry.npmjs.org/prettier/-/prettier-2.6.2.tgz",
"integrity": "sha512-PkUpF+qoXTqhOeWL9fu7As8LXsIUZ1WYaJiY/a7McAQzxjk82OF0tibkFXVCDImZtWxbvojFjerkiLb0/q8mew==",
"dev": true,
"peer": true
},I guess it's what most people will experience so we have to live with this for now.
Fair enough 👍🏻 |
|
Moving this to "Review in Progress" column. |
I take your point, but as you observe this is a learning exercise. The presumed audience is developers new to React and maybe even new to JavaScript, having come from a PHP background. I'm trying in the course to introduce concepts gradually and in this instance show them a way to do it that they might already be familiar with, or at least able to understand the code, and then refactor it to show them a more "React way" of doing the same thing which might initially seem conceptually alien. I don't know, I think this is a better way but I'm open to persuasion that your suggestion of introducing useBlockProps earlier in the course might be better for the learner.
Is that theme dependent? When using Twenty Twenty-Two the drop cap doesn't seem to be available. In any case it's a learning exercise and demonstrates how to use
That's coz there aren't any! 😄 The example you mentioned in your earlier comment was a transitory thing which was replaced with a better version in the course. That has been removed now because, as you said, it was confusing for the learner and I now realise it was actually a bit redundant. The other instance where an experimental component is mentioned is a box out in this lesson where it's referenced in case the learner has come across it elsewhere and they're discouraged from using it. Do you think it's better not to mention it at all? Thanks for your kind comments on the other items, and thanks again for taking the time to review the course. |
I had to check how
This is a way to mark a HTML element as a block wrapper in the editor. It means that this is where all additional HTML attributes get injected to ensure that the block integrates seamlessly with all the UI elements like block toolbar, inspector controls, and related interactions. The most important code looks as follows: return {
tabIndex: 0,
...wrapperProps,
...props,
ref: mergedRefs,
id: `block-${ clientId }${ htmlSuffix }`,
role: 'document',
'aria-label': blockLabel,
'data-block': clientId,
'data-type': name,
'data-title': blockTitle,
className: classnames(
// The wp-block className is important for editor styles.
classnames( 'block-editor-block-list__block', {
'wp-block': ! isAligned,
'has-block-overlay': hasOverlay,
} ),
className,
props.className,
wrapperProps.className,
useBlockClassNames( clientId ),
useBlockDefaultClassName( clientId ),
useBlockCustomClassName( clientId ),
useBlockMovingModeClassNames( clientId )
),
style: { ...wrapperProps.style, ...props.style },
};There is a ton happening here, but what's most important is that you better pass all props through this function (yes, it's also React hook) to ensure that the block editor is able to merge everything together. Now, let me explain a few issues with the code example included like: return (
<>
<RichText
{...useBlockProps()}
tagName="p"
onChange={onChangeContent}
value={attributes.content}
placeholder={__("Enter some text here...")}
style={{
columnCount: attributes.columnCount,
color: attributes.style.color.text,
background: attributes.style.color.background,
}}
/>
</>
);
The other challenge is that const blockProps = useBlockProps({
style={{
columnCount: attributes.columnCount,
color: attributes.style.color.text,
background: attributes.style.color.background,
}}
});
return (
<RichText
{...blockProps}
tagName="p"
onChange={onChangeContent}
value={attributes.content}
placeholder={__("Enter some text here...")}
/>
);The developer experience is suboptimal here because it's hard to explain that Aside: the following code would also work: const blockProps = useBlockProps({
style={{
columnCount: attributes.columnCount,
color: attributes.style.color.text,
background: attributes.style.color.background,
}}
tagName="p"
onChange={onChangeContent}
value={attributes.content}
placeholder={__("Enter some text here...")}
});
return (
<RichText {...blockProps} />
);I don't think it's used this way for core blocks. It's all about the mental mode where we mix block wrapper props with the props specific to the React element that we enhance. I wish we had a better story for it. The interesting aspect here is that if we were to pass an
Yes, theme authors can disable certain features, including all other shared controls that are featured in the course. The same thing can happen to colors or padding when they get disabled. The other story is that block style variations need better integration with the features that themes can control with
I see what you did. You were faster than I was able to process the course 😄 I would keep an eye on that and double-check with folks new to the block development. As I mentioned before, it would be great to show only stable APIs in all educational material and hide experiments for internal usage in the Gutenberg plugin. I also can see how the code copied for the custom React component can work as a way to teach that you can build your controls, too. |
|
@mburridge I'm finally able to focus on reviewing the course. I will leave notes here on a per-module basis, in separate comments. Introduction and Module 1General comments: Great introduction and first module! I like how you keep it light, engaging, and focused on the learning outcomes. I'm excited to move through the rest of the course. Specific comments Introduction
Module 1What is a block?
Understand the structure of the project
|
Module 2Make the block interactive
It's not clear that the block props are always passed to the Edit (and save) function, and that they contain the attributes object from the block.json (among other things). So a sentence or two explaining this might be helpful. I do this in my Attributes tutorial (which you can see here at about 2:25 on the video)
It's not clear where this should be in the Edit function, so it might be ideal to clarify that it needs to be before the return but inside the Edit function. Add ‘Block Supports’ controls
Define default settings in block.json
|
|
Michael, let me just take this opportunity to congratulate you again on doing a superb job. It is no easy feat to create a course like this!! Here is some feedback from my side: Solid introduction! Module 1 Understand the structure of your project Build and run your project Change 'the' to 'then' I would suggest breaking this sentence up into two parts Create custom inspector panel controls Heading and paragraph should be capital letters = Heading block / Paragraph block Add more configuration options I would suggest breaking this sentence up into two parts: Configuration options for the separator I suggest breaking up this sentence into two parts Add Style Variations Conditionally display controls Wrapping up Quizzes: |
|
Thanks @ryanwelcher.
@juanmaguitar thanks for the comprehensive feedback. I'll take a look at it in detail after the weekend. |
|
All the lessons in Modules 1 – 4 now each have at least one quiz or activity Reviews are ongoing and we are receiving great feedback. With the addition of the interactive elements, we can consider the course as ready for publication (subject to ongoing reviews and modifications) |
|
Some more comments/suggestions from my review of the course: At Make the block interactive I would use some headings to make more clear the explanations over each one of the files. Something like...
|
|
Hey @mburridge Please validate feedback: #1835 |
|
Hey @mburridge Yes, it is good to get direct feedback from students. If you agree with the feedback and feel it is valid, you could update the course with the points raised. Some feedback might not be valid, actionable, or within the scope of the course. Hope that makes sense. |
|
WP 6.4 WordPress/gutenberg#52579 please review |
courtneyr-dev
added
the
hacktoberfest
|
@courtneyr-dev do you have anything specific you think needs to be updated on this course due to the Interactivity API? As far as I remember, this course does not use either the File block or Navigation block, which is what the linked Gutenberg issue is about. |
|
@jonathanbossenger I'm not entirely sure but wasn't sure if it was related. In part, it is hard to sus out what is contained within a course when I'm blasting through many GitHub issues. This is part of why it is a challenge to know what inside courses should be updated. I do think these likely are though: Key Make Posts/GitHub/Trac Issue(s): |
kaitohm
added
fields-done
and removed
Review 1 complete
hacktoberfest
|
The interactivity API will probably land in WordPress in version 6.5. Once that's happened, we can look at adding content about it to one of the developer learning pathways, probably the intermediate plugin developer pathway. Therefore I am closing this ticket for now. |
No description provided.
The text was updated successfully, but these errors were encountered: