search

WordPress / Learn

WordPress.org Learn - The canonical source for the code and content behind https://learn.WordPress.org
274 stars 100 forks source link

Using the Create Block tool - Tutorial #857

Closed jonathanbossenger closed 9 months ago

jonathanbossenger commented 2 years ago

Topic Description

Set up and use the Create Block tool to scaffold a new block plugin.

Related Resources

Links to related content on Learn, HelpHub, DevHub, GitHub Gutenberg Issues, DevNotes, etc.

Guidelines

Review the [team guidelines] (https://make.wordpress.org/training/handbook/guidelines/)

Tutorial Development Checklist

jonathanbossenger commented 2 years ago

https://user-images.githubusercontent.com/180629/181045380-ee4e922b-2bc5-415f-aae6-2e5946399a53.mp4

hlashbrooke commented 2 years ago

This is excellent @jonathanbossenger - really solid work!

Other than to say "yes - I love this!" I don't have any direct feedback on the content (which is to say that I'm happy for this to be shipped).

One thing to note is that, since we don't have the capability to add chapters to videos, it would be good to have a list of timestamps in the video description indicating when you start different things - like installing prereqs on Mac, installing prereqs on Windows, using create-block, etc.

Great work!

jonathanbossenger commented 2 years ago

it would be good to have a list of timestamps in the video description indicating when you start different things - like installing prereqs on Mac, installing prereqs on Windows, using create-block, etc.

That's a great idea, thanks @hlashbrooke. I'll make sure to add this to the video description.

gziolo commented 2 years ago

The part covering nvm, while useful, isn't mandatory here. In fact, it makes it feel like the process is more complex. In practice, you can have any LTS (Long Term Support) version (14, 16, 18) of Node.js and npm bundled with those versions. Maybe, it would be enough to emphasize the version labeled LTS visible at the presented https://nodejs.org website?

We definitely don't want people to use the identical versions of Node.js and npm as in the Gutenberg repository. The documentation page presented Development Environment is specific to the Gutenberg project. All the tools for building blocks should work with any Node LTS version. There are some nuances to the development process in the project where there are nearly 1000 code contributors 😄

I think that in the Block Editor Handbook, it was a good call to have two separate sections for creating a block and setting the development environment. I saw that there is a tutorial for Local WordPress Installations, and I believe that eventually, it would be nice to split this tutorial into two videos, too. If someone has Node.js installed, then they most likely can skip to the 5th minute of the video.

Anyway, I guess the tutorial is excellent as is if you don’t plan to have more videos covering how to use other JS tools helpful for building blocks.

gziolo commented 2 years ago

I was wondering what's the overall plan for the learning materials regarding building blocks. The version included in the video is great to show how quickly you can create any block, but it's just the beginning. One thing that I found interesting in the video is that you presented the link to the npm package, which isn't easy to discover in the Block Editor Handbook:

https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/

The content of this video tutorial is very similar to the first page from the Getting Started section that I personally used in every public communication:

https://developer.wordpress.org/block-editor/getting-started/create-block/

It's also linked in the handbook from the intro page:

https://developer.wordpress.org/block-editor

Screenshot 2022-07-27 at 11 09 13

and the getting started page:

https://developer.wordpress.org/block-editor/getting-started

Screenshot 2022-07-27 at 11 06 15

One thing that might be worth mentioning is that when you don't provide the plugin/block slug, then it's possible to customize several settings for plugin and block. See the video I used during my recent talk at WordCamp EU:

https://www.youtube.com/watch?v=YWGtHRSlxlY

westnz commented 2 years ago

Fantastic work Jonathan. Everything flows very nicely.

Review the recording from 7:19 - 7:20. Should it be block code or block clode 😃

I like your systematic approach.

jonathanbossenger commented 2 years ago

@gziolo thank you for your detailed feedback.

The part covering nvm, while useful, isn't mandatory here. In fact, it makes it feel like the process is more complex. In practice, you can have any LTS (Long Term Support) version (14, 16, 18) of Node.js and npm bundled with those versions. Maybe, it would be enough to emphasize the version labeled LTS visible at the presented https://nodejs.org/ website?

That's a valid point. The purpose of this video is to introduce someone brand new to block development, but who may also want to contribute to the block editor itself. Also, if folks want to use wp-env, So my thinking was to focus on the specific version currently needed for Gutenberg development, which means the developer is already on the right version.

Do you think it would be better to say something like this?

You can use any LTS version of Node.js greater than version 12 to use create-block [screen shows different LTS versions], but as the Gutenberg project is using version 14, for the purpose of this video tutorial let's install version 14

I was wondering what's the overall plan for the learning materials regarding building blocks.

There is no general overall plan as yet, but the long-term goal is to cover as much as possible of the Block Developer Handbook.

I'm starting with this series of 4 videos, with the short-term goal of presenting the quickest way to convert an existing shortcode plugin to a block-enabled plugin.

  1. Using create-block to create a new block (this tutorial, foundational information)
  2. Use code scaffolded from create-block to convert an existing shortcode to a block - https://github.com/WordPress/Learn/issues/858
  3. Styling your block - https://github.com/WordPress/Learn/issues/859
  4. Working with attributes - https://github.com/WordPress/Learn/issues/860

There is also a Block development course that @mburridge and @westnz are working on, that's a more detailed approach to teaching how to develop blocks.

As will all educational content, most of what we're working on in the short term are foundational, and we can create future tutorial videos, online workshops, and courses that cover more advanced topics, that build on top of the foundations of this content.

One thing that might be worth mentioning is that when you don't provide the plugin/block slug, then it's possible to customize several settings for plugin and block.

This is a good example of what I'm talking about, eventually, I'd love to do a more detailed online workshop on create-block, covering what all the different options do. However, for a shorter 5-10 minute format of the tutorial video, I have to limit what I can cover.

jonathanbossenger commented 2 years ago

@westnz thanks for the feedback

Review the recording from 7:19 - 7:20. Should it be block code or block clode 😃

I had hoped no one would notice 😁

adamziel commented 2 years ago

It flowed smoothly @jonathanbossenger. Thank you for creating great educational resources! I have similar notes as @westnz and @gziolo, but not much besides that. Once it's all ready, I'll be happy to share this with folks. Keep it up! 👍

jonathanbossenger commented 2 years ago

Updated to include notes on Node.js versions.

https://user-images.githubusercontent.com/180629/183867938-5f33c3cf-5921-4aa2-ad5d-2883d0327ddb.mp4

jonathanbossenger commented 2 years ago

Published https://learn.wordpress.org/tutorial/using-the-create-block-tool/

jonathanbossenger commented 1 year ago

Reopening this issue as this content is a year old, and needs to be updated for the changes that have occurred over the last year.

jonathanbossenger commented 9 months ago

This will be covered in the module on block development in the beginner developer learning pathway.