-
Notifications
You must be signed in to change notification settings - Fork 86
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Block: Improve in file documentation to make it easier to edit content #107
Conversation
@@ -126,6 +126,7 @@ Feature: WordPress block code scaffolding | |||
Then the {THEME_DIR}/blocks/fight-club.php file should exist |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
2 tests are failing, need to be updated.
2 more tests need to verify if style.css
file was created.
templates/block-block-js.mustache
Outdated
* 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
templates/block-block-js.mustache
Outdated
* which is then serialized by Gutenberg into `post_content`. | ||
* @see https://wordpress.org/gutenberg/handbook/block-edit-save/#save | ||
* | ||
* @return {Object} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@return needs more love.
@danielbachhuber - how do you regenerate README file? I tried
|
@gziolo Don't worry about it if you can't figure it out. We can do so at the very end. |
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 :) |
templates/block-block-js.mustache
Outdated
/** | ||
* 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}}' ), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IIRC the domain
is not handled yet and I wonder if the i18n module is ready for third-party usage
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should I remove domain
part or leave it as it is? I think it doesn't harm to have 2nd param :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
The same issue applies to the API. I fix |
@gziolo To refresh the README file:
|
I removed 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. |
templates/block-block-js.mustache
Outdated
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
* | ||
* @param {Object} [props] Properties passed from the editor. | ||
* @return {Element} Element to render. | ||
*/ | ||
edit: function( props ) { | ||
return el( |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As this scaffolding serves as an onboarding tool as well, it would be useful to also document what the el()
does here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍
I added more inline comments to make the generated code better documented. |
There's still no documentation for the |
Ah, sorry, nvm my previous comment, I just failed to look properly. |
Block: Improve in file documentation to make it easier to edit content
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):
In addition, I added the following changes:
supportsHtml
.Screenshots
In the editor:
In the post: