Block: Improve in file documentation to make it easier to edit content #107

gziolo · 2017-12-20T13:23:45Z

This PR tries to improve the experience for the future block implementers by adding inline documentation based on the Gutenberg Handbook.

Initial suggestion came from @danielbachhuber in #88 (comment):

Another idea to throw into the mix: Add jsDoc to the scaffolded edit and save functions that provides an introductory overview to the functions and then links to the corresponding handbook docs.

In addition, I added the following changes:

Added CSS styles loaded for both editor and fronted.
Added a note that a recommended way is to generate a block inside a plugin.
Fixed a few linting errors for generated PHP and JS files.
Update API to use a new way of setting supportsHtml.

Screenshots

In the editor:

In the post:

gziolo · 2017-12-20T13:24:34Z

features/scaffold-block.feature

@@ -126,6 +126,7 @@ Feature: WordPress block code scaffolding
    Then the {THEME_DIR}/blocks/fight-club.php file should exist


2 tests are failing, need to be updated.

2 more tests need to verify if style.css file was created.

gziolo · 2017-12-20T13:25:07Z

templates/block-block-js.mustache

+		 * This represents what the editor will render when the block is used.
+		 * @see https://wordpress.org/gutenberg/handbook/block-edit-save/#edit
+		 *
+		 * @param {Object} props Properties passed to the


@param and @return need more love.

gziolo · 2017-12-20T13:25:19Z

templates/block-block-js.mustache

+		 * which is then serialized by Gutenberg into `post_content`.
+		 * @see https://wordpress.org/gutenberg/handbook/block-edit-save/#save
+		 *
+		 * @return {Object}


@return needs more love.

gziolo · 2017-12-20T13:29:43Z

@danielbachhuber - how do you regenerate README file?

I tried wp scaffold package-readme but apparently failed with the following:

Error: 'package-readme' is not a registered subcommand of 'scaffold'. See 'wp help scaffold' for available subcommands.

danielbachhuber · 2017-12-20T13:32:56Z

@gziolo Don't worry about it if you can't figure it out. We can do so at the very end.

gziolo · 2017-12-21T11:34:12Z

Travis is finally happy, I added a few improvements and addressed all my comments. It needs to have README file regenerated before it gets merged. It's ready for a review.

I want to add support for another template in the follow-up PR.

Another thing I would like to explore is to add a flag for a plugin scaffolding command to optionally generate a block. Does it even make sense?

I want to have all that included in v1.5, so expect my PRs in the middle of January :)

youknowriad · 2017-12-21T13:10:54Z

templates/block-block-js.mustache

+		/**
+		 * This is the display title for your block, which can be translated with `i18n` functions.
+		 * The block inserter will show this name.
+		 */
 		title: __( '{{title_ucfirst}}', '{{textdomain}}' ),


IIRC the domain is not handled yet and I wonder if the i18n module is ready for third-party usage

Should I remove domain part or leave it as it is? I think it doesn't harm to have 2nd param :)

Yes, I should remove the domain part from JS file. Related documentation in Gutenberg: https://github.com/WordPress/gutenberg/tree/master/i18n#usage.

Note that you will not need to specify domain for the strings.

youknowriad

This looks solid to me. I worry a bit about the links to the handbooks in case we change the urls and forget to update here.

Great Work @gziolo

gziolo · 2017-12-21T13:29:43Z

This looks solid to me. I worry a bit about the links to the handbooks in case we change the urls and forget to update here.

The same issue applies to the API. I fix supportHTML changes in this PR.

schlessera · 2017-12-21T14:00:03Z

@gziolo To refresh the README file:

Install the wp-cli/scaffold-package-command package:

wp package install wp-cli/scaffold-package-command

Run the wp scaffold package-readme command in the command's root folder:

wp scaffold package-readme . --force

gziolo · 2017-12-22T10:14:03Z

I removed textdomain option as it turned out to be obsolete.

README is regenerated to use the updated PHPDoc. @schlessera thanks for sharing steps to do it 👍

It should be good to merge. I retested with the recent changes, everything works as expected.

schlessera · 2017-12-23T07:12:08Z

templates/block-block-js.mustache

 		icon: '{{dashicon}}',

 		{{/dashicon}}
+		/**
+		 * Blocks are grouped into categories to help users browse and discover them.
+		 * The core provided categories are `common`, `embed`, `formatting`, `layout` and `widgets`.


This seems grammatically off to me. Depending on the intended meaning, I'd suggest either of these two:

The provided core categories

The categories provided by core

schlessera · 2017-12-23T07:18:08Z

templates/block-block-js.mustache

+		 *
+		 * @param {Object} [props] Properties passed from the editor.
+		 * @return {Element}       Element to render.
+		 */
 		edit: function( props ) {
 			return el(


As this scaffolding serves as an onboarding tool as well, it would be useful to also document what the el() does here.

gziolo · 2017-12-27T16:10:12Z

I added more inline comments to make the generated code better documented.

schlessera · 2017-12-29T10:31:12Z

There's still no documentation for the el() part, which is rather obscure for newcomers. Would you mind adding a short comment for that as well?

schlessera · 2017-12-29T10:34:07Z

Ah, sorry, nvm my previous comment, I just failed to look properly.
This looks good to me now, merging.

Block: Improve in file documentation to make it easier to edit content

gziolo commented Dec 20, 2017

View reviewed changes

gziolo changed the title ~~[WIP] Block: Improve in file documentation to make it easier to edit content~~ Block: Improve in file documentation to make it easier to edit content Dec 21, 2017

youknowriad reviewed Dec 21, 2017

View reviewed changes

gziolo added 2 commits December 22, 2017 10:31

Block: Improve in file documentation to make it easier to edit content

c74032f

Regenerate README with updates for block scaffolding command

a839bf3

schlessera requested changes Dec 23, 2017

View reviewed changes

Document all functions used in the generated block code

ecd39b1

schlessera added command:scaffold-block scope:documentation labels Dec 29, 2017

schlessera approved these changes Dec 29, 2017

View reviewed changes

schlessera added this to the 1.1.2 milestone Dec 29, 2017

schlessera merged commit 13b3ccb into wp-cli:master Dec 29, 2017

gziolo deleted the update/scaffold-block branch December 29, 2017 16:57

gziolo mentioned this pull request Jan 12, 2018

Add a dynamic render template to the block scaffold #108

Closed

danielbachhuber pushed a commit that referenced this pull request Nov 18, 2022

Merge pull request #107 from gziolo/update/scaffold-block

26b068b

Block: Improve in file documentation to make it easier to edit content

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Block: Improve in file documentation to make it easier to edit content #107

Block: Improve in file documentation to make it easier to edit content #107

gziolo commented Dec 20, 2017 •

edited

Loading

gziolo Dec 20, 2017

gziolo Dec 20, 2017

gziolo Dec 20, 2017

gziolo commented Dec 20, 2017

danielbachhuber commented Dec 20, 2017

gziolo commented Dec 21, 2017

youknowriad Dec 21, 2017

gziolo Dec 21, 2017

gziolo Dec 22, 2017

youknowriad left a comment

gziolo commented Dec 21, 2017 •

edited

Loading

schlessera commented Dec 21, 2017 •

edited

Loading

gziolo commented Dec 22, 2017 •

edited

Loading

schlessera Dec 23, 2017

schlessera Dec 23, 2017

gziolo Dec 23, 2017

gziolo commented Dec 27, 2017

schlessera commented Dec 29, 2017

schlessera commented Dec 29, 2017

		@@ -126,6 +126,7 @@ Feature: WordPress block code scaffolding
		Then the {THEME_DIR}/blocks/fight-club.php file should exist

Block: Improve in file documentation to make it easier to edit content #107

Block: Improve in file documentation to make it easier to edit content #107

Conversation

gziolo commented Dec 20, 2017 • edited Loading

Screenshots

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Dec 20, 2017

danielbachhuber commented Dec 20, 2017

gziolo commented Dec 21, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad left a comment

Choose a reason for hiding this comment

gziolo commented Dec 21, 2017 • edited Loading

schlessera commented Dec 21, 2017 • edited Loading

gziolo commented Dec 22, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Dec 27, 2017

schlessera commented Dec 29, 2017

schlessera commented Dec 29, 2017

gziolo commented Dec 20, 2017 •

edited

Loading

gziolo commented Dec 21, 2017 •

edited

Loading

schlessera commented Dec 21, 2017 •

edited

Loading

gziolo commented Dec 22, 2017 •

edited

Loading