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

First pass at docs for the Widgets Block Editor #31577

Merged
merged 4 commits into from
May 8, 2021

Conversation

noisysocks
Copy link
Member

Here's my first pass at some docs for the Widgets Block Editor. This checks off many of the items in #25759.

I'm not really familiar with how docs/manifest.json works so please let me know if I did something wrong there.

@noisysocks noisysocks added [Type] Developer Documentation Documentation for developers [Feature] Widgets Screen The block-based screen that replaced widgets.php. [Block] Legacy Widget Affects the Legacy Widget Block - used for displaying Classic Widgets [Feature] Widgets Customizer Ability to add and edit blocks in Customize → Widgets. labels May 7, 2021
@github-actions
Copy link

github-actions bot commented May 7, 2021

Size Change: +364 B (0%)

Total Size: 1.31 MB

Filename Size Change
build/annotations/index.js 2.93 kB +1 B (0%)
build/block-directory/index.js 6.59 kB -8 B (0%)
build/block-editor/index.js 116 kB +179 B (0%)
build/block-editor/style-rtl.css 13 kB -42 B (0%)
build/block-editor/style.css 13 kB -40 B (0%)
build/block-library/blocks/post-featured-image/style-rtl.css 119 B +19 B (+19%) ⚠️
build/block-library/blocks/post-featured-image/style.css 119 B +19 B (+19%) ⚠️
build/block-library/index.js 142 kB +21 B (0%)
build/block-library/style-rtl.css 9.62 kB +170 B (+2%)
build/block-library/style.css 9.63 kB +170 B (+2%)
build/blocks/index.js 47 kB -2 B (0%)
build/components/index.js 188 kB +817 B (0%)
build/compose/index.js 9.92 kB -37 B (0%)
build/customize-widgets/index.js 5.79 kB -28 B (0%)
build/customize-widgets/style-rtl.css 698 B +9 B (+1%)
build/customize-widgets/style.css 699 B +9 B (+1%)
build/data-controls/index.js 830 B +1 B (0%)
build/data/index.js 7.22 kB -3 B (0%)
build/edit-navigation/index.js 13.6 kB -68 B (0%)
build/edit-navigation/style-rtl.css 2.81 kB -72 B (-2%)
build/edit-navigation/style.css 2.81 kB -73 B (-3%)
build/edit-post/index.js 333 kB -173 B (0%)
build/edit-post/style-rtl.css 6.79 kB -187 B (-3%)
build/edit-post/style.css 6.78 kB -183 B (-3%)
build/edit-site/index.js 26.1 kB -33 B (0%)
build/edit-site/style-rtl.css 4.79 kB -113 B (-2%)
build/edit-site/style.css 4.78 kB -113 B (-2%)
build/edit-widgets/index.js 12.6 kB +20 B (0%)
build/edit-widgets/style-rtl.css 3.02 kB +45 B (+2%)
build/edit-widgets/style.css 3.03 kB +45 B (+2%)
build/editor/index.js 60.5 kB -1 B (0%)
build/element/index.js 3.44 kB -1 B (0%)
build/format-library/index.js 5.68 kB -1 B (0%)
build/i18n/index.js 3.73 kB +1 B (0%)
build/nux/index.js 2.31 kB +4 B (0%)
build/reusable-blocks/index.js 2.56 kB +2 B (0%)
build/rich-text/index.js 11.9 kB +10 B (0%)
ℹ️ View Unchanged
Filename Size Change
build/a11y/index.js 1.11 kB 0 B
build/api-fetch/index.js 2.42 kB 0 B
build/autop/index.js 2.28 kB 0 B
build/blob/index.js 673 B 0 B
build/block-directory/style-rtl.css 993 B 0 B
build/block-directory/style.css 995 B 0 B
build/block-library/blocks/archives/editor-rtl.css 61 B 0 B
build/block-library/blocks/archives/editor.css 60 B 0 B
build/block-library/blocks/audio/editor-rtl.css 58 B 0 B
build/block-library/blocks/audio/editor.css 58 B 0 B
build/block-library/blocks/audio/style-rtl.css 112 B 0 B
build/block-library/blocks/audio/style.css 112 B 0 B
build/block-library/blocks/block/editor-rtl.css 161 B 0 B
build/block-library/blocks/block/editor.css 161 B 0 B
build/block-library/blocks/button/editor-rtl.css 475 B 0 B
build/block-library/blocks/button/editor.css 474 B 0 B
build/block-library/blocks/button/style-rtl.css 515 B 0 B
build/block-library/blocks/button/style.css 515 B 0 B
build/block-library/blocks/buttons/editor-rtl.css 315 B 0 B
build/block-library/blocks/buttons/editor.css 315 B 0 B
build/block-library/blocks/buttons/style-rtl.css 368 B 0 B
build/block-library/blocks/buttons/style.css 368 B 0 B
build/block-library/blocks/calendar/style-rtl.css 208 B 0 B
build/block-library/blocks/calendar/style.css 208 B 0 B
build/block-library/blocks/categories/editor-rtl.css 84 B 0 B
build/block-library/blocks/categories/editor.css 83 B 0 B
build/block-library/blocks/categories/style-rtl.css 79 B 0 B
build/block-library/blocks/categories/style.css 79 B 0 B
build/block-library/blocks/code/style-rtl.css 90 B 0 B
build/block-library/blocks/code/style.css 90 B 0 B
build/block-library/blocks/columns/editor-rtl.css 190 B 0 B
build/block-library/blocks/columns/editor.css 190 B 0 B
build/block-library/blocks/columns/style-rtl.css 422 B 0 B
build/block-library/blocks/columns/style.css 422 B 0 B
build/block-library/blocks/cover/editor-rtl.css 603 B 0 B
build/block-library/blocks/cover/editor.css 604 B 0 B
build/block-library/blocks/cover/style-rtl.css 1.22 kB 0 B
build/block-library/blocks/cover/style.css 1.22 kB 0 B
build/block-library/blocks/embed/editor-rtl.css 486 B 0 B
build/block-library/blocks/embed/editor.css 486 B 0 B
build/block-library/blocks/embed/style-rtl.css 401 B 0 B
build/block-library/blocks/embed/style.css 400 B 0 B
build/block-library/blocks/file/editor-rtl.css 301 B 0 B
build/block-library/blocks/file/editor.css 300 B 0 B
build/block-library/blocks/file/frontend.js 773 B 0 B
build/block-library/blocks/file/style-rtl.css 255 B 0 B
build/block-library/blocks/file/style.css 255 B 0 B
build/block-library/blocks/freeform/editor-rtl.css 2.45 kB 0 B
build/block-library/blocks/freeform/editor.css 2.45 kB 0 B
build/block-library/blocks/gallery/editor-rtl.css 704 B 0 B
build/block-library/blocks/gallery/editor.css 705 B 0 B
build/block-library/blocks/gallery/style-rtl.css 1.06 kB 0 B
build/block-library/blocks/gallery/style.css 1.05 kB 0 B
build/block-library/blocks/group/editor-rtl.css 160 B 0 B
build/block-library/blocks/group/editor.css 160 B 0 B
build/block-library/blocks/group/style-rtl.css 57 B 0 B
build/block-library/blocks/group/style.css 57 B 0 B
build/block-library/blocks/heading/editor-rtl.css 129 B 0 B
build/block-library/blocks/heading/editor.css 129 B 0 B
build/block-library/blocks/heading/style-rtl.css 76 B 0 B
build/block-library/blocks/heading/style.css 76 B 0 B
build/block-library/blocks/html/editor-rtl.css 281 B 0 B
build/block-library/blocks/html/editor.css 281 B 0 B
build/block-library/blocks/image/editor-rtl.css 717 B 0 B
build/block-library/blocks/image/editor.css 716 B 0 B
build/block-library/blocks/image/style-rtl.css 476 B 0 B
build/block-library/blocks/image/style.css 478 B 0 B
build/block-library/blocks/latest-comments/style-rtl.css 281 B 0 B
build/block-library/blocks/latest-comments/style.css 282 B 0 B
build/block-library/blocks/latest-posts/editor-rtl.css 137 B 0 B
build/block-library/blocks/latest-posts/editor.css 137 B 0 B
build/block-library/blocks/latest-posts/style-rtl.css 523 B 0 B
build/block-library/blocks/latest-posts/style.css 522 B 0 B
build/block-library/blocks/legacy-widget/editor-rtl.css 557 B 0 B
build/block-library/blocks/legacy-widget/editor.css 557 B 0 B
build/block-library/blocks/list/style-rtl.css 63 B 0 B
build/block-library/blocks/list/style.css 63 B 0 B
build/block-library/blocks/media-text/editor-rtl.css 176 B 0 B
build/block-library/blocks/media-text/editor.css 176 B 0 B
build/block-library/blocks/media-text/style-rtl.css 492 B 0 B
build/block-library/blocks/media-text/style.css 489 B 0 B
build/block-library/blocks/more/editor-rtl.css 434 B 0 B
build/block-library/blocks/more/editor.css 434 B 0 B
build/block-library/blocks/navigation-link/editor-rtl.css 617 B 0 B
build/block-library/blocks/navigation-link/editor.css 619 B 0 B
build/block-library/blocks/navigation-link/style-rtl.css 94 B 0 B
build/block-library/blocks/navigation-link/style.css 94 B 0 B
build/block-library/blocks/navigation/editor-rtl.css 1.32 kB 0 B
build/block-library/blocks/navigation/editor.css 1.31 kB 0 B
build/block-library/blocks/navigation/style-rtl.css 1.27 kB 0 B
build/block-library/blocks/navigation/style.css 1.27 kB 0 B
build/block-library/blocks/nextpage/editor-rtl.css 395 B 0 B
build/block-library/blocks/nextpage/editor.css 395 B 0 B
build/block-library/blocks/page-list/editor-rtl.css 239 B 0 B
build/block-library/blocks/page-list/editor.css 240 B 0 B
build/block-library/blocks/page-list/style-rtl.css 167 B 0 B
build/block-library/blocks/page-list/style.css 167 B 0 B
build/block-library/blocks/paragraph/editor-rtl.css 157 B 0 B
build/block-library/blocks/paragraph/editor.css 157 B 0 B
build/block-library/blocks/paragraph/style-rtl.css 247 B 0 B
build/block-library/blocks/paragraph/style.css 248 B 0 B
build/block-library/blocks/post-author/editor-rtl.css 209 B 0 B
build/block-library/blocks/post-author/editor.css 209 B 0 B
build/block-library/blocks/post-author/style-rtl.css 183 B 0 B
build/block-library/blocks/post-author/style.css 184 B 0 B
build/block-library/blocks/post-comments-form/style-rtl.css 140 B 0 B
build/block-library/blocks/post-comments-form/style.css 140 B 0 B
build/block-library/blocks/post-comments/style-rtl.css 362 B 0 B
build/block-library/blocks/post-comments/style.css 362 B 0 B
build/block-library/blocks/post-content/editor-rtl.css 139 B 0 B
build/block-library/blocks/post-content/editor.css 139 B 0 B
build/block-library/blocks/post-excerpt/editor-rtl.css 73 B 0 B
build/block-library/blocks/post-excerpt/editor.css 73 B 0 B
build/block-library/blocks/post-excerpt/style-rtl.css 69 B 0 B
build/block-library/blocks/post-excerpt/style.css 69 B 0 B
build/block-library/blocks/post-featured-image/editor-rtl.css 338 B 0 B
build/block-library/blocks/post-featured-image/editor.css 338 B 0 B
build/block-library/blocks/post-title/style-rtl.css 60 B 0 B
build/block-library/blocks/post-title/style.css 60 B 0 B
build/block-library/blocks/preformatted/style-rtl.css 103 B 0 B
build/block-library/blocks/preformatted/style.css 103 B 0 B
build/block-library/blocks/pullquote/editor-rtl.css 183 B 0 B
build/block-library/blocks/pullquote/editor.css 183 B 0 B
build/block-library/blocks/pullquote/style-rtl.css 318 B 0 B
build/block-library/blocks/pullquote/style.css 318 B 0 B
build/block-library/blocks/query-loop/editor-rtl.css 83 B 0 B
build/block-library/blocks/query-loop/editor.css 82 B 0 B
build/block-library/blocks/query-loop/style-rtl.css 315 B 0 B
build/block-library/blocks/query-loop/style.css 317 B 0 B
build/block-library/blocks/query-pagination-numbers/editor-rtl.css 122 B 0 B
build/block-library/blocks/query-pagination-numbers/editor.css 121 B 0 B
build/block-library/blocks/query-pagination/editor-rtl.css 270 B 0 B
build/block-library/blocks/query-pagination/editor.css 262 B 0 B
build/block-library/blocks/query-pagination/style-rtl.css 168 B 0 B
build/block-library/blocks/query-pagination/style.css 168 B 0 B
build/block-library/blocks/query-title/editor-rtl.css 86 B 0 B
build/block-library/blocks/query-title/editor.css 86 B 0 B
build/block-library/blocks/query/editor-rtl.css 131 B 0 B
build/block-library/blocks/query/editor.css 132 B 0 B
build/block-library/blocks/quote/style-rtl.css 169 B 0 B
build/block-library/blocks/quote/style.css 169 B 0 B
build/block-library/blocks/rss/editor-rtl.css 201 B 0 B
build/block-library/blocks/rss/editor.css 202 B 0 B
build/block-library/blocks/rss/style-rtl.css 290 B 0 B
build/block-library/blocks/rss/style.css 290 B 0 B
build/block-library/blocks/search/editor-rtl.css 189 B 0 B
build/block-library/blocks/search/editor.css 189 B 0 B
build/block-library/blocks/search/style-rtl.css 359 B 0 B
build/block-library/blocks/search/style.css 362 B 0 B
build/block-library/blocks/separator/editor-rtl.css 99 B 0 B
build/block-library/blocks/separator/editor.css 99 B 0 B
build/block-library/blocks/separator/style-rtl.css 251 B 0 B
build/block-library/blocks/separator/style.css 251 B 0 B
build/block-library/blocks/shortcode/editor-rtl.css 512 B 0 B
build/block-library/blocks/shortcode/editor.css 512 B 0 B
build/block-library/blocks/site-logo/editor-rtl.css 440 B 0 B
build/block-library/blocks/site-logo/editor.css 441 B 0 B
build/block-library/blocks/site-logo/style-rtl.css 154 B 0 B
build/block-library/blocks/site-logo/style.css 154 B 0 B
build/block-library/blocks/social-link/editor-rtl.css 164 B 0 B
build/block-library/blocks/social-link/editor.css 165 B 0 B
build/block-library/blocks/social-links/editor-rtl.css 796 B 0 B
build/block-library/blocks/social-links/editor.css 795 B 0 B
build/block-library/blocks/social-links/style-rtl.css 1.32 kB 0 B
build/block-library/blocks/social-links/style.css 1.33 kB 0 B
build/block-library/blocks/spacer/editor-rtl.css 308 B 0 B
build/block-library/blocks/spacer/editor.css 308 B 0 B
build/block-library/blocks/spacer/style-rtl.css 48 B 0 B
build/block-library/blocks/spacer/style.css 48 B 0 B
build/block-library/blocks/table/editor-rtl.css 478 B 0 B
build/block-library/blocks/table/editor.css 478 B 0 B
build/block-library/blocks/table/style-rtl.css 485 B 0 B
build/block-library/blocks/table/style.css 485 B 0 B
build/block-library/blocks/tag-cloud/editor-rtl.css 118 B 0 B
build/block-library/blocks/tag-cloud/editor.css 118 B 0 B
build/block-library/blocks/tag-cloud/style-rtl.css 94 B 0 B
build/block-library/blocks/tag-cloud/style.css 94 B 0 B
build/block-library/blocks/template-part/editor-rtl.css 551 B 0 B
build/block-library/blocks/template-part/editor.css 550 B 0 B
build/block-library/blocks/term-description/editor-rtl.css 90 B 0 B
build/block-library/blocks/term-description/editor.css 90 B 0 B
build/block-library/blocks/text-columns/editor-rtl.css 95 B 0 B
build/block-library/blocks/text-columns/editor.css 95 B 0 B
build/block-library/blocks/text-columns/style-rtl.css 166 B 0 B
build/block-library/blocks/text-columns/style.css 166 B 0 B
build/block-library/blocks/verse/style-rtl.css 87 B 0 B
build/block-library/blocks/verse/style.css 87 B 0 B
build/block-library/blocks/video/editor-rtl.css 569 B 0 B
build/block-library/blocks/video/editor.css 570 B 0 B
build/block-library/blocks/video/style-rtl.css 169 B 0 B
build/block-library/blocks/video/style.css 169 B 0 B
build/block-library/common-rtl.css 1.26 kB 0 B
build/block-library/common.css 1.26 kB 0 B
build/block-library/editor-rtl.css 9.62 kB 0 B
build/block-library/editor.css 9.61 kB 0 B
build/block-library/reset-rtl.css 506 B 0 B
build/block-library/reset.css 507 B 0 B
build/block-library/theme-rtl.css 692 B 0 B
build/block-library/theme.css 693 B 0 B
build/block-serialization-default-parser/index.js 1.3 kB 0 B
build/block-serialization-spec-parser/index.js 3.06 kB 0 B
build/components/style-rtl.css 16.2 kB 0 B
build/components/style.css 16.2 kB 0 B
build/core-data/index.js 12.1 kB 0 B
build/date/index.js 31.8 kB 0 B
build/deprecated/index.js 738 B 0 B
build/dom-ready/index.js 576 B 0 B
build/dom/index.js 4.62 kB 0 B
build/edit-post/classic-rtl.css 454 B 0 B
build/edit-post/classic.css 454 B 0 B
build/editor/style-rtl.css 3.95 kB 0 B
build/editor/style.css 3.95 kB 0 B
build/escape-html/index.js 739 B 0 B
build/format-library/style-rtl.css 637 B 0 B
build/format-library/style.css 639 B 0 B
build/hooks/index.js 1.76 kB 0 B
build/html-entities/index.js 628 B 0 B
build/is-shallow-equal/index.js 710 B 0 B
build/keyboard-shortcuts/index.js 1.65 kB 0 B
build/keycodes/index.js 1.43 kB 0 B
build/list-reusable-blocks/index.js 2.06 kB 0 B
build/list-reusable-blocks/style-rtl.css 629 B 0 B
build/list-reusable-blocks/style.css 628 B 0 B
build/media-utils/index.js 3.08 kB 0 B
build/notices/index.js 1.07 kB 0 B
build/nux/style-rtl.css 718 B 0 B
build/nux/style.css 716 B 0 B
build/plugins/index.js 2 kB 0 B
build/primitives/index.js 1.03 kB 0 B
build/priority-queue/index.js 791 B 0 B
build/react-i18n/index.js 924 B 0 B
build/redux-routine/index.js 2.82 kB 0 B
build/reusable-blocks/style-rtl.css 225 B 0 B
build/reusable-blocks/style.css 225 B 0 B
build/server-side-render/index.js 1.64 kB 0 B
build/shortcode/index.js 1.68 kB 0 B
build/token-list/index.js 847 B 0 B
build/url/index.js 1.95 kB 0 B
build/viewport/index.js 1.28 kB 0 B
build/warning/index.js 1.13 kB 0 B
build/widgets/index.js 1.68 kB 0 B
build/wordcount/index.js 1.24 kB 0 B

compressed-size-action

@talldan
Copy link
Contributor

talldan commented May 7, 2021

I'm not really familiar with how docs/manifest.json works so please let me know if I did something wrong there.

Hey @noisysocks. I don't see that updated in this PR, so I think it may have been overwritten.

IIRC, one of the toc.json or the manifest.json is updated manually and the other is auto-generated from that change. Given the manifest changes aren't present, that's probably the one that's auto-generated from the manually updated toc.json.

@noisysocks
Copy link
Member Author

Aha, oops, I updated manifest.json instead of toc.json. Fixed 🙂

…and the wording more consistent and less verbose
Copy link
Contributor

@draganescu draganescu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made a few changes, not essential. The docs are great @noisysocks thanks for writing them!

@mrleemon
Copy link
Contributor

mrleemon commented Jun 20, 2021

In the "Add a block transform" section of this doc, the example is using a "from" transform. Shouldn't this be a "to" transform, @noisysocks ?

https://github.com/WordPress/gutenberg/blob/trunk/docs/how-to-guides/widgets/legacy-widget-block.md#2-add-a-block-transform

@talldan
Copy link
Contributor

talldan commented Jun 21, 2021

A from transform seems correct to me, because it's from the specified legacy widget to the current block type.

If it were a to transform it'd have to be defined on the legacy widget block itself.

@mrleemon
Copy link
Contributor

Ok. I'm trying to add a transform in a legacy widget I developed years ago and I cannot get it to work either way (from or to) as it doesn't appear in the Transform dropdown. I must be doing something wrong.

@talldan
Copy link
Contributor

talldan commented Jun 21, 2021

@mrleemon Feel free to share your transform code and I'll see if I can spot anything.

@mrleemon
Copy link
Contributor

Here it is:

transforms: {
    from: [
        {
            type: 'block',
            blocks: [ 'my/newblock' ],
            isMatch: ( { idBase, instance } ) => {
                if ( ! instance?.raw ) {
                    return false;
                }
                return idBase === 'mylegacywidget';
            },
            transform: ( { instance } ) => {
                const transformedBlock = createBlock(
                    'my/newblock',
                    {
                        count: instance.raw.count,
                        dropdown: instance.raw.dropdown,
                    }
                );
                if ( ! instance.raw?.title ) {
                    return transformedBlock;
                }
                return [
                    createBlock( 'core/heading', {
                        content: instance.raw.title,
                    } ),
                    transformedBlock,
                ];
            },
        },
    ]
},

The block and the legacy widget have two boolean attributes: count and dropdown. The widget also has a title that I need to convert to a heading block and put before the actual new block.

Thanks in advance

@talldan
Copy link
Contributor

talldan commented Jun 21, 2021

@mrleemon The blocks array should be [ 'core/legacy-widget' ]. For a from transform it indicates the block(s) you want to transform from.

The block you're transforming to is indicated by the block definition that the transform appears within (and the block type specified in the transform function).

This is the reverse of a to transform where it works the other way around.

@mrleemon
Copy link
Contributor

Thanks, that was it!
Now, the option to transform the legacy widget to the new block appears on the Transform dropdown.
Although the widget can be converted now, I'm getting an error (Error loading block: Invalid parameters: attributes) when doing so, but I think it has nothing to do with the transform code. I'll investigate.
Thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Block] Legacy Widget Affects the Legacy Widget Block - used for displaying Classic Widgets [Feature] Widgets Customizer Ability to add and edit blocks in Customize → Widgets. [Feature] Widgets Screen The block-based screen that replaced widgets.php. [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants