Tutorial: Create your First App with Gutenberg Data #38250
Conversation
adamziel
added
[Type] Developer Documentation
There was a problem hiding this comment.
I like this tutorial a lot. I didn't read fully but somethings standout to me: the repeating of wp.element.createElement is not great and aside JSX, it's seem that you're using ESnext in the examples. It makes me wonder whether it's better to just use JSX in the examples and have a note at the beginning or the end that links to the build setup config tutorial.
| wp_register_script( | ||
| 'my-first-gutenberg-app', | ||
| plugins_url( 'my-first-gutenberg-app/app.js' ), | ||
| array( 'wp-components', 'wp-data', 'wp-core-data' ), |
There was a problem hiding this comment.
should we explain what each one of the dependencies provide for our example?
There was a problem hiding this comment.
Good point! I added a short comment for each
|
Stellar work, @adamziel 🥇 Will this tutorial be part of the Gutenberg examples repo? I usually find it helpful to see finished example projects and how all pieces come together. P.S. I assumed that you need to wrap your app in |
That would be great 👍
I agree that tutorials should promote JSX and ES Modules in the first place. It would be good to double check whether they still provide tye version without JSX. The first exposure to coding tutorials is here: https://github.com/WordPress/gutenberg/tree/trunk/docs/getting-started/create-block I haven’t checked the tutorial yet but I love the idea ❤️ |
|
I just realized it's not obvious how to review the rendered markdown and not just the code: Rendered markdown
|
|
Size Change: +26 B (0%) Total Size: 1.14 MB
ℹ️ View Unchanged
|
|
I improved the screenshots, polished the grammar, and added finished examples. Here's the rich-text preview of the tutorial so far. Can y'all see anything else that can be improved before merging the first part of it?
@Mamaduka I would love that! And I think we're pretty close to making it happen by merging this PR :-)
@youknowriad I went for JSX-first examples with a hidden compiled snippet. I think that's the best of both worlds, as in we have readability and convenience at the same time. As for using ESnext in the examples – many features are widely supported by browsers so I think that's fine as long as it's not sprinkled with JSX.
@gziolo I went for
It's now a part of this PR! :-) @getdave I know you had the following notes:
Pages unfortunately don't have
How would this look like? I didn't know how to introduce this topic as we're not building a new resolver at this point, only calling a selector that happens to have a related resolver. |
|
|
||
| Congratulations! You are now ready to start building the app! | ||
|
|
||
| ## Readability vs Convenience |
There was a problem hiding this comment.
I think you can skip this whole paragraph or link to some existing page that covers the same topic.
A good reference would be also a tutorial that @getdave contributed for the standalone block editor:
Those are advanced tutorials and they should be using the most efficient syntax so in my opinion the build step is essential here.
There was a problem hiding this comment.
I agree in principle, but I think of this tutorial as more of a first step towards understanding advanced Gutenberg concepts. It can benefit from a build tool but I don't think it should require one. I'm thinking of myself here – I'm pretty impatient and I would instinctively look for a different tutorial with less pre-requisites.
That being said, let's see if I can make this section more succinct.
There was a problem hiding this comment.
That's why we always try to pair the tutorial with https://github.com/WordPress/gutenberg-examples so you don't have to write a single line of code to run it 😄
There was a problem hiding this comment.
Ooh that's great, thank you for sharing! I'll look into that
|
First, this is a fantastic resource and I'm so happy you've taken the time to put it together. I think it'll be a great addition to https://github.com/WordPress/gutenberg-examples. My only concern, which has been shared by others already, is we're not using JSX and a build process. I completely understand the concept of just wanting to start building but we have been discussing moving all code examples to use JSX first ( see WordPress/gutenberg-examples#171 and #35776 ) and adding a new, advanced tutorial that doesn't that seems to be a bit of a step backward in that regards. We also miss out on driving home just how powerful and versatile the From my own personal experience having built applications like this in the past, I would always choose JSX for readability and the |
|
Is there a general tutorial on "getting setup with |
|
Fantastic suggestions @getdave, I merged all of them – thank you so much! I think we're almost there. I removed the compiled bits and focused on JSX as almost everyone here suggested. I will polish the code examples a bit more to use imports instead of |
…te easy querying of WP data.
adamziel
force-pushed
the
doc/first-app-with-gutenberg-data
branch
from
ac4277d
to
91246da
Compare
|
@youknowriad Yeah I don't like having the code in this repo AND in gutenberg-examples. I removed the samples from this PR, but there is a small downside: you can no longer review how the current step looks like when finished, only the entire tutorial. I'm considering adding |
|
Great work on the updates Adam. Thanks for being so receptive to feedback. |
Co-authored-by: Dave Smith <getdavemail@gmail.com>
Co-authored-by: Dave Smith <getdavemail@gmail.com>
…s to the selector and hasFinished resolution - thank you @get_dave!
…ess/gutenberg into doc/first-app-with-gutenberg-data
|
Alright, does anyone dare to approve this PR and the code sample in gutenberg-examples? :D |
It feels a bit too much, maybe it's fine to just have these temporary steps like we have them now inline in the tutorial. |
|
Good stuff! 👍 For this to show up on the block editor handbook site you need to add it to the |
The fourth part of the Create your First App with Gutenberg Data tutorial, this time focused on creating new records. See #38250. Co-authored-by: Dave Smith <getdavemail@gmail.com>
Description
This PR proposes a tutorial gently introducing the user to Gutenberg Data's concepts through building a small application.
It is a spin-off of #37615 dedicated for new users. I would like to follow up with one or two more advanced materials.
For now I drafted the Readme, setup, and the part where we build the list view for WordPress pages. I'd like to stop and collect feedback before writing the rest of it. Perhaps we could merge this tutorial part-by-part instead of all at once.
Kudos to @getdave @bph @ironprogrammer @ryanwelcher @mkaz @youknowriad @gziolo @talldan @tellthemachines @draganescu for their feedback so far!
cc @draganescu @gziolo @youknowriad @talldan @annezazu @noisysocks