Skip to content
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

Docs: add tutorial for creating a custom block editor instance #20410

Merged
merged 16 commits into from Mar 6, 2020

Conversation

@getdave
Copy link
Contributor

getdave commented Feb 24, 2020

Description

I wrote a "tutorial" (more a "walkthrough guide") on creating a custom instance of the block editor within WP Admin.

This is highly relevant as the Full Site Editing project editor starts to expand the editor beyond Post content.

This tutorial was originally published on a standalone repo, but having spoken with @youknowriad he's suggested it might be useful as a public tutorial within the Gutenberg docs.

This PR:

  • ports over the content.
  • rewords as required to make suitable for Gutenberg project docs.

Note that the code for the tutorial still lives in the original repo. I wonder whether this should be moved within the Gutenberg project somehow to ensure it is preserved.

How has this been tested?

This tutorial has been reviewed by members of the Core team including @epiqueras and @youknowriad.

To test you can:

  • Read through the tutorial.
  • Check it has been worded in a way that is suitable for inclusion in public-facing docs.
  • Check for spelling/grammar errors.
  • Ensure appropriate links are in place.

Types of changes

New feature (non-breaking change which adds functionality).

Checklist:

  • My code is tested.
  • My code follows the WordPress code style.
  • My code follows the accessibility standards.
  • My code has proper inline documentation.
  • I've included developer documentation if appropriate.
  • I've updated all React Native files affected by any refactorings/renamings in this PR.
@github-actions

This comment has been minimized.

Copy link

github-actions bot commented Feb 24, 2020

Size Change: 0 B

Total Size: 863 kB

ℹ️ View Unchanged
Filename Size Change
build/a11y/index.js 1.01 kB 0 B
build/annotations/index.js 3.43 kB 0 B
build/api-fetch/index.js 3.39 kB 0 B
build/autop/index.js 2.58 kB 0 B
build/blob/index.js 620 B 0 B
build/block-directory/index.js 6.02 kB 0 B
build/block-directory/style-rtl.css 760 B 0 B
build/block-directory/style.css 760 B 0 B
build/block-editor/index.js 104 kB 0 B
build/block-editor/style-rtl.css 10.5 kB 0 B
build/block-editor/style.css 10.5 kB 0 B
build/block-library/editor-rtl.css 7.26 kB 0 B
build/block-library/editor.css 7.26 kB 0 B
build/block-library/index.js 115 kB 0 B
build/block-library/style-rtl.css 7.5 kB 0 B
build/block-library/style.css 7.51 kB 0 B
build/block-library/theme-rtl.css 669 B 0 B
build/block-library/theme.css 671 B 0 B
build/block-serialization-default-parser/index.js 1.65 kB 0 B
build/block-serialization-spec-parser/index.js 3.1 kB 0 B
build/blocks/index.js 57.7 kB 0 B
build/components/index.js 191 kB 0 B
build/components/style-rtl.css 15.5 kB 0 B
build/components/style.css 15.5 kB 0 B
build/compose/index.js 5.75 kB 0 B
build/core-data/index.js 10.6 kB 0 B
build/data-controls/index.js 1.03 kB 0 B
build/data/index.js 8.22 kB 0 B
build/date/index.js 5.36 kB 0 B
build/deprecated/index.js 772 B 0 B
build/dom-ready/index.js 569 B 0 B
build/dom/index.js 3.06 kB 0 B
build/edit-post/index.js 91.3 kB 0 B
build/edit-post/style-rtl.css 8.69 kB 0 B
build/edit-post/style.css 8.69 kB 0 B
build/edit-site/index.js 4.64 kB 0 B
build/edit-site/style-rtl.css 2.48 kB 0 B
build/edit-site/style.css 2.48 kB 0 B
build/edit-widgets/index.js 4.42 kB 0 B
build/edit-widgets/style-rtl.css 2.59 kB 0 B
build/edit-widgets/style.css 2.58 kB 0 B
build/editor/editor-styles-rtl.css 325 B 0 B
build/editor/editor-styles.css 327 B 0 B
build/editor/index.js 43.8 kB 0 B
build/editor/style-rtl.css 3.98 kB 0 B
build/editor/style.css 3.98 kB 0 B
build/element/index.js 4.45 kB 0 B
build/escape-html/index.js 734 B 0 B
build/format-library/index.js 7.11 kB 0 B
build/format-library/style-rtl.css 502 B 0 B
build/format-library/style.css 502 B 0 B
build/hooks/index.js 1.92 kB 0 B
build/html-entities/index.js 622 B 0 B
build/i18n/index.js 3.48 kB 0 B
build/is-shallow-equal/index.js 710 B 0 B
build/keyboard-shortcuts/index.js 2.3 kB 0 B
build/keycodes/index.js 1.68 kB 0 B
build/list-reusable-blocks/index.js 2.99 kB 0 B
build/list-reusable-blocks/style-rtl.css 226 B 0 B
build/list-reusable-blocks/style.css 226 B 0 B
build/media-utils/index.js 4.85 kB 0 B
build/notices/index.js 1.57 kB 0 B
build/nux/index.js 3.01 kB 0 B
build/nux/style-rtl.css 616 B 0 B
build/nux/style.css 613 B 0 B
build/plugins/index.js 2.54 kB 0 B
build/primitives/index.js 1.49 kB 0 B
build/priority-queue/index.js 780 B 0 B
build/redux-routine/index.js 2.84 kB 0 B
build/rich-text/index.js 14.3 kB 0 B
build/server-side-render/index.js 2.55 kB 0 B
build/shortcode/index.js 1.7 kB 0 B
build/token-list/index.js 1.27 kB 0 B
build/url/index.js 4 kB 0 B
build/viewport/index.js 1.61 kB 0 B
build/warning/index.js 1.14 kB 0 B
build/wordcount/index.js 1.18 kB 0 B

compressed-size-action

@getdave

This comment has been minimized.

Copy link
Contributor Author

getdave commented Feb 24, 2020

Question - as it's quite long, should we split this tutorial up over multiple (interlinked) files with one per "section"? This might make it easier to consume.

@gziolo

This comment has been minimized.

Copy link
Member

gziolo commented Feb 24, 2020

Wow, this is an awesome tutorial to include 🥇

Question - as it's quite long, should we split this tutorial up over multiple (interlinked) files with one per "section"? This might make it easier to consume.

@mkaz or @nosolosw - might have the best answer here as they authored several existing tutorials.

@gziolo

This comment has been minimized.

Copy link
Member

gziolo commented Feb 24, 2020

@getdave – it would be nice to optimize the size of media included because it's something all contributors will have to download. Ideally, all those assets are hosted outside of git so we don't keep all versions in its history.

@getdave

This comment has been minimized.

Copy link
Contributor Author

getdave commented Feb 24, 2020

Wow, this is an awesome tutorial to include 🥇

Thanks 🙇

it would be nice to optimize the size of media included because it's something all contributors will have to download.

I've resized to 800px in width and run through an image optimizer. Now slimmed down.

Ideally, all those assets are hosted outside of git so we don't keep all versions in its history.

Do we have a preference for where?

@mkaz

This comment has been minimized.

Copy link
Member

mkaz commented Feb 24, 2020

@getdave @gziolo I've split between one long post, or multiple pages. I think my preference now is a single long post with anchor links on the headings that make them bookmarkable so you can link/jump to any section.

As far as assets, we don't have a great solution. Previously we've attached them to Github tickets and then referred to the absolute URL being served from Github. If you have author writes, you can also upload to the developer.wordpress.org blog media library and use the absolute URL from there.

@gziolo

This comment has been minimized.

Copy link
Member

gziolo commented Feb 25, 2020

it would be nice to optimize the size of media included because it's something all contributors will have to download. Ideally, all those assets are hosted outside of git so we don't keep all versions in its history.

As far as assets, we don't have a great solution. Previously we've attached them to Github tickets and then referred to the absolute URL being served from Github. If you have author writes, you can also upload to the developer.wordpress.org blog media library and use the absolute URL from there.

@mapk or @karmatosed – what's the preferred approach for design-related assets? We should follow the same approach.

@aduth

This comment has been minimized.

Copy link
Member

aduth commented Feb 26, 2020

Regardless of precedent, I would strongly advocate against including image assets in the repository, since this adds significant non-recoverable, non-diffable growth to the downloaded clone size of the repository, which already exceeds 300MB. At least in the context of GitHub, it's fairly straight-forward and consistent to use GitHub's image uploading (via comment box or issue form). It's maybe questionable in how we sync this content to WordPress.org. It should still work, I expect. Alternatives like Cloudup, WordPress.com, or WordPress.org (for those with access) could be possible as well.

@chrisvanpatten

This comment has been minimized.

Copy link
Member

chrisvanpatten commented Feb 26, 2020

@getdave could your sample repo be a candidate to move into the gutenberg-examples repo?

@mkaz

This comment has been minimized.

Copy link
Member

mkaz commented Mar 5, 2020

I think this would be a good candidate to move to a new section I just created in the developer documents ( PR #20666 ) for Gutenberg as a Platform.

I believe @youknowriad discussed it previously with me about needing a spot for documents on developers using Gutenberg Packages, not just for extending within WordPress but for any app development. I feel your tutorial fits this nicely.

Your tutorial is great, and provides a ton of knowledge to learn the platform, but better in an advanced section. The tutorials section feels like it should focus more on things a WordPress developer would do for creating a plugin to extend the editor or other parts of WP.

Thoughts?

@getdave

This comment has been minimized.

Copy link
Contributor Author

getdave commented Mar 6, 2020

I've split between one long post, or multiple pages. I think my preference now is a single long post with anchor links on the headings that make them bookmarkable so you can link/jump to any section.

@mkaz All done. Please could you 👍 if you're happy?

I think this would be a good candidate to move to a new section I just created in the developer documents ( PR #20666 ) for Gutenberg as a Platform.

@mkaz Agreed. Could you let me know the anticipated timeline for when your PR might land?

I'm keen to get this tutorial merged as soon as I can so things don't change underneath me 😄

@mkaz

This comment has been minimized.

Copy link
Member

mkaz commented Mar 6, 2020

I think the PR #20666 is ready to go now, its more of a stub page for things to be added to as we go. If you can give me a 👍 there I'll merge it in. Then you can adjust this PR to move into that new directory and we'll be good to ship.

Does that work?

@getdave

This comment has been minimized.

Copy link
Contributor Author

getdave commented Mar 6, 2020

About to sort out media files

@mkaz

This comment has been minimized.

Copy link
Member

mkaz commented Mar 6, 2020

@getdave 👍 thanks for the approval #20666 is merged. Ready for you to move into that new dir.

@getdave getdave force-pushed the add/block-editor-tutorial-to-docs branch from d2768ad to 0ee024c Mar 6, 2020
@getdave

This comment has been minimized.

Copy link
Contributor Author

getdave commented Mar 6, 2020

@mkaz Shall I just create platform/tutorials/custom-block-editor and link to that from the main README.md in /platform?

@mkaz
mkaz approved these changes Mar 6, 2020
Copy link
Member

mkaz left a comment

This is looking good, thanks! :shipit:

@getdave getdave merged commit 9eb5eb8 into master Mar 6, 2020
3 checks passed
3 checks passed
build
Details
pull-request-automation
Details
Travis CI - Pull Request Build Passed
Details
@getdave getdave deleted the add/block-editor-tutorial-to-docs branch Mar 6, 2020
@github-actions github-actions bot added this to the Gutenberg 7.7 milestone Mar 6, 2020
@Soean

This comment has been minimized.

Copy link
Member

Soean commented Mar 9, 2020

@getdave Great tutorial!

I can't find it in the block editor handbook: https://developer.wordpress.org/block-editor/
I think we need to add it to the manifest and toc json file in the docs folder, right?

@mkaz

This comment has been minimized.

Copy link
Member

mkaz commented Mar 9, 2020

@Soean Added in: #20749

It is also listed on the bottom of this page: https://developer.wordpress.org/block-editor/developers/platform/

But the link doesn't work and everything looks right, is that because it's not in the Table of Contents?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants
You can’t perform that action at this time.