Docs: Create a Block tutorial #22831
Conversation
gziolo
added
the
[Feature] Block Directory
docs/designers-developers/developers/tutorials/create-block/author-experience.md
Outdated
Show resolved
Hide resolved
|
Feedback. enviornment x 2 (written twice) = environment This page is really well written! Flows well! Code Editor What about mentioning a few other code editors? As you said it is a personal choice but it is always good to list a few to choose from to inform the user of some alternatives. Nicely written! It would be nice to link to Chrome developer tools in addition to Firefox. To mention both. Nicely done! Well explained! This was not clear for me. It could be broken down some more. To me it felt that the page lacked some more details. It was nice that you linked to additional resources. Works well! Works. Anything else. Could be to add various components into the block. Next up will be to test this out. |
|
@paaljoachim Thank you for the comprehensive set of feedback. I've addressed all the items you listed and refined the tutorial further. I appreciate you walking through it, and look forward to feedback as you test out implementing. Thank you. |
|
Size Change: +5.59 kB (0%) Total Size: 1.13 MB
ℹ️ View Unchanged
|
|
Hi Marcus @mkaz I looked at the adjusted documentation and noticed this typo under Additional Components. You can visually browse the compoents (should be components) and what their implementation looks like using the Storybook tool published at https://wordpress.github.io/gutenberg The documentation looks really good! |
There was a problem hiding this comment.
I reviewed two files only, but I plan to check other files in the upcoming days as well. I’m really excited about this new tutorial, so far it’s looking great. Ideally, it’s reviewed by several folks with little knowledge about building blocks to validate it’s helpful 😃
On the technical level, do you think we should update the default template of @wordpress/create-block to scaffold the final version of this tutorial?
docs/designers-developers/developers/tutorials/create-block/author-experience.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/author-experience.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/author-experience.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## A Better Solution | ||
|
|
||
| Replacing the Placeholder and TextControl when it is selected or not is jarring and not an ideal situation for this block. This was mainly used to illustrate what can be done depending on your block. It is important to think about the author's experience using the block. |
There was a problem hiding this comment.
This could be rephrased a bit. My first reaction was: if it’s jarring why I even had to think about it. Can we start with thinking about the best experience, emphasis that placeholders are usually the way to go, it’s one of principles of blocks but here we can simplify it with CSS?
There was a problem hiding this comment.
I introduced the placeholder with how images and embeds handle it, which works well for images, but not for text. The goal was to show how people might think about the problem seeing other references.
I rephrase and we see if that is better.
docs/designers-developers/developers/tutorials/create-block/author-experience.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/readme.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/readme.md
Outdated
Show resolved
Hide resolved
|
Going through this as a non developer. There is a lot of confusion during the first step. Development Tools What does “bootstrap a block” mean? The tools are used to take the JavaScript we are going to write, which is in a syntax that the browser can not run, and transpile it into a syntax it can. Can instead become: The tools are used to take the JavaScript we are going to write and transpile (transpile explaination ) it into a syntax the browser can run. ———— NB! All links need to open in a new tab! So one does not loose the tutorial in relation to clicking the links. download Nodejs (link) ——> https://nodejs.org/en/download/ (download the installer for the operating system that you use.) It also packaged for most package managers. = This means what? I went ahead and downloaded the Nodejs and installed it before I read the recommendation about using Homebrew package tool for the Mac. brew install nodejs = the js part is outside the code syntax. I am confused about the Homebrew package tool part. Going to the Homebrew site: The documentation says: I am confused about the two install methods one mentioned in the sentence right above here and one suggested on the Homebrew web site. — NPM usually comes bundled with the above installs. = That is confusing. The above speaks about downloading and installing, and now I read that the NPM also bundles the above installs. However you install Nodejs… ? I am not clear about the different methods used.
I think that was the Development Tools page. I stopped up there, and will start again after the docs have been updated. Have a great weekend! |
- Add clarification around TextControl use - Fix classname back to root element - Rephrase on how to better stylize text - Simplify quick start, emphasize activation - Add CLI prompts for questions
- Call out package managers is an alternative - Be clear about what is needed per platform
|
@paaljoachim I think I addressed your concerns here. I called out that the package managers is an alternative to using the Node installer. I also specified clearly which platform what matches with. Thanks for the feedback, keep it coming. |
|
Open links in a new tab? Freeflowing thoughts as I understand the instructions. "The tools are used to convert the JavaScript we are going to write into a format that browsers can run. This is called transpiling or the build step." New: On Mac, Homebrew (link) is a popular package manager. After having downloaded Homebrew follow our instructions on install. Open terminal and type: brew install nodejs On Windows, Chocolatey (link) is a popular package manager. After having downloaded Chocolatey follow our instructions on install. Open terminal and type: choco install nodejs On Linux, you should confirm NPM is also installed. In some systems it is bundled separately and you may need to explicitly install it. For example, on Ubuntu, or Debian systems you can install using: apt install nodejs npm If you already have a package manager installed, you can download Nodejs (link) directly from the main website and install. "Alternatively, if you use a package manager, a node package is avilable (typo) for most package managers." "....otherwise step through whatever part of the tutorial you need." |
I don’t think we use it in other places. Besides, it’s something you can do yourself with keyboard modifiers or with mouse interactions built into OS. |
|
Great Marcus! It is slow going but the documentation is getting better for each revision! |
|
Restarting the test. I installed Homebrew this time. Reinstalled Docker. I added this: My guess was that the original Nodejs install affected the wp-env, so I looked for ways to remove nodejs from my OSX system. I came across this: https://www.positronx.io/how-to-uninstall-node-js-and-npm-from-macos/ and followed it. I then reinstalled Homebrew. Then checked to see if node -v and npm -v had been reinstalled. They had not. Right now I am looking at https://changelog.com/posts/install-node-js-with-homebrew-on-os-x and following the instructions there. I got this message at the end: I typed Then received: Right now I am not sure how to proceed. |
|
I uninstalled Homebrew. Reinstalled using https://brew.sh/ Then typed: I added EDIT: Another try. This seemed to have worked: I ran: Then reinstalled Homebrew Node and npm are now showing up: node -v |
|
Next step is installing: These are the messages I received in terminal: Checking: I am a present time not able to get the wp-env installed through terminal. |
|
Looking at alternatives such as Local. WordPress Plugin (doc page) "If you do not plan to use wp-env change to your local WordPress plugin directory; if you do plan to use wp-env start from any directory for your project." ---> "Run the following command to generate plugin files:" ---> If using Local or another software. What would be the correct terminal command be? For instance based on the above example. "The generated plugin should now be listed on the Plugins admin page in your WordPress install. If you are using wp-env, see Development Enviornment (typo) setup, then you should now run:" If using Local? Start the site up in Local and enter the WordPress site. |
|
@paaljoachim I added heading to the plugin section, so it says which each step is, plus made it clear the options for each one giving an A and B for Local vs. wp-env |
|
A work around suggested by Marcus. I pasted this code into terminal: It seemed to work alright until this point: The above code asked me to create one of the files listed. I typed this into terminal: I received no confirmation that the file was created. This time it seemed to work. I tried again to install Closed terminal and reopened. There seemed to be some errors, but I closed terminal and reopened and ran Closed and reopened terminal. Pasted: The same errors as seen further above came back. One error that is seen in the longer terminal message above containing the errors is: I followed the instructions here: https://anansewaa.com/install-command-line-tools-on-macos-catalina/ to (re)install Xcode. Testing this: https://stackoverflow.com/questions/34617452/how-to-update-xcode-from-command-line No updates are available. I have logged into: https://developer.apple.com/download/more/ to download the latest stable Xcode. Version 11.5. It is currently downloading the 7.6GB zip file. I also downloaded the Command Line Tools for Xcode 11.5GM Seed.dmg |
|
@paaljoachim for typos and different phrasing you can propose the change directly in the UI. This way it’s going to be much easier to apply (anyone with member can do it) and your contributions will be attributed to you out of the box. See: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review |
|
I've linked up the tutorial to table of contents, and added a link at the bottom of each page to the next. My preference is to get this merged and up and then iterate with additional information, it will be easier to track individual changes and suggestions -vs- continuing on a large set of docs at once. |
|
@mkaz, is there a way to put this tutorial in a temporary folder in docs and iterate with follow-up tasks? In the meantime, I helped @coreymckrill to merge this change where we generate Earlier this week, I backported to WordPress core new method for block registration that will make it possible to register blocks from PHP using If it's merged, some other folks could help with the individual steps of this tutorial. |
@gziolo I can remove it from Table of Contents, we could still merge, it would not get published since it wouldn't be in the manifest. So it'd be in the repo but not published to Block Editor handbook. Is that what you were thinking? |
There was a problem hiding this comment.
Yes, it works for me, let's do it :)
@paaljoachim, any concerns?
|
I have not yet tested the most recent version so I do not know if that works. |
|
As the initial link to the documentation has changed. The documentation is now here: https://github.com/WordPress/gutenberg/tree/master/docs/designers-developers/developers/tutorials/create-block |
|
Btw I am using Mac OSX 10.15.5. (macOS Catalina).
As soon as the next iteration PR has been setup. Let me know and I will begin to give feedback there. |
|
One more thing. A user who turns into a developer needs to know how to set up the Gutenberg development environment. So the very first tutorial would be setting up a local development environment for Gutenberg. It should contain various information which has been setup up to this point. With a trouble shooting section at the end. At the end of setting up the Gutenberg development environment it branches out to (adds links to) Contributing to Gutenberg. Can contain: Setting up a PR. Contributing to an existing PR. Code reviews. Etc.... (adds links to) Bottom line. It all starts with setting up the Gutenberg environment. Kinda like a breadcrumbs path containing parents and children. |
|
We have the Setting up the base/foundation for local WordPress Development Environment here: #23593 -- But where are the docs for Creating a Block? |
|
@paaljoachim I need approval and then I can merge #23593 after that is in, I can link up the Create a Block tutorial. Right now it's only in GitHub and not published publicly. |
Description
Creates a new "Create a Block" tutorial that uses the new create-block package and scripts. The tutorial walks through the entire setup from developer environment to a completed block that accepts a message and stylizes it.
Related: #22151
How has this been tested?
Go through tutorial, does it make sense? work?
Types of changes
Documentation. View on the branch here
Still to do