Add block collections #17609

scruffian · 2019-09-26T13:37:31Z

Description

As proposed in #16866, this adds a new function registerBlockCollection( namespace, title, icon = {} );

This enables blocks to be added to both collections and categories, ensuring that blocks can be put in the category that they make the most sense in, but also make it possible to see all the blocks coming from a single source.

namespace is matched against a block prefix.
title shows in the block inserter.
icon will show alongside the title, if defined

How has this been tested?

Tested in Chrome on a .org installation with no other plugins.

Screenshots

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.

gziolo

This is definitely a good direction. It raises some questions like:

what do we about all currently registered custom categories?
do we still want to allow to register custom categories?
how do we encourage plugin developers to use collections instead of categories?

We still need documentation, a note in the changelog and unit tests for new APIs.

gziolo · 2019-09-26T14:40:43Z

packages/blocks/src/api/registration.js

+ * @param {Object} tite      The title to show in the inserter
+ * @param {Object} icon      The icon to show in the inserter
+ *
+ * @return {?WPBlock} The block, if it has been successfully registered;


The description for the return value needs to be updated.

gziolo · 2019-09-26T14:42:47Z

packages/block-editor/src/components/inserter/menu.js

@@ -30,6 +30,7 @@ import {
 } from '@wordpress/components';
 import {
 	getCategories,
+	getCollections,


Wouldn't it be more reliable to get both collections and categories through withSelect HOC?

gziolo · 2019-09-26T14:43:10Z

docs/designers-developers/developers/data/data-core-blocks.md

@@ -195,6 +207,10 @@ _Returns_

 <!-- START TOKEN(Autogenerated actions) -->

+<a name="addBlockCollection" href="#addBlockCollection">#</a> **addBlockCollection**
+
+Undocumented declaration.


Documentation is missing here.

I added it, I guess this will update automatically?

npm run docs:build should update this document.

scruffian · 2019-09-26T15:05:26Z

Thanks for the review @gziolo. Some thoughts:

do we still want to allow to register custom categories?
what do we about all currently registered custom categories?

I think there is still value in the custom categories. The way I see it this just adds another option for block developers, but they can continue doing it how they are without a problem.

how do we encourage plugin developers to use collections instead of categories?

I'll add it to the docs.

scruffian · 2019-09-26T16:20:28Z

Another question this raises is, should we should blocks in both sections when you search, for example:

scruffian · 2019-09-27T13:15:24Z

@gziolo I added a test. Is that sufficient?

gziolo · 2019-10-07T10:35:52Z

packages/blocks/src/api/registration.js

@@ -1,4 +1,4 @@
-/* eslint no-console: [ 'error', { allow: [ 'error' ] } ] */
+/* eslint no-8: [ 'error', { allow: [ 'error' ] } ] */


It doesn't look like an expected change.

gziolo · 2019-10-07T10:37:18Z

@youknowriad and @mtias - can you share your feedback on this PR?

youknowriad

Left a small comment but I like the addition 👍

youknowriad · 2019-10-07T10:41:16Z

packages/blocks/src/api/collections.js

+ */
+export function getCollections() {
+	return select( 'core/blocks' ).getCollections();
+}


Is this necessary? Can't we rely on selectors instead? (Selectors are reactive and not global functions).
I know we do the same mistake for other things like "categories", "block types"... but ideally, we don't continue the trend for new APIs.

Happy to make the change, but I'm not sure what it should be. I just copied the other (bad) examples!

The idea is that we don't really need this function.

components can call select( 'core/blocks' ).getCollections() directly in withSelect or useSelect

gziolo · 2019-10-07T10:46:36Z

One more question, how this would work for blocks registered on the server? Do you think this should be something which should be handled only on the front-end?

registerBlockCollection( namespace, title, icon = {} );

One more thing, as far as I remember, all the APIs that register something take an object as 2nd param. Should we follow the same pattern here? In general, it's more flexible as it allows to easily introduce more options in the future.

gziolo · 2019-10-25T14:20:54Z

packages/blocks/src/api/registration.js

+ * @param {Object} icon      The icon to show in the inserter
+ *
+ */
+export function registerBlockCollection( namespace, title, icon ) {


All the existing public API methods which register something use settings object as 2nd param, it would be great to align, see:

gutenberg/packages/rich-text/src/register-format-type.js

Line 36 in f8b62bd

export function registerFormatType( name, settings ) {

gutenberg/packages/plugins/src/api/index.js

Line 109 in f8b62bd

export function registerPlugin( name, settings ) {

gutenberg/packages/blocks/src/api/registration.js

Line 119 in f8b62bd

export function registerBlockType( name, settings ) {

All of them offer unregister* function as well which returns the registered object for more control for 3rd party plugings.

scruffian · 2019-12-04T13:23:00Z

One more question, how this would work for blocks registered on the server? Do you think this should be something which should be handled only on the front-end?

I think having it front-end only is fine for now. We can add a server side option for it if there's a demand.

scruffian · 2019-12-19T15:01:10Z

@youknowriad I've rebased this and fixed all the conflicts. Thanks for looking.

draganescu

The collection appears as documented, the test collection still needs to be removed.

draganescu · 2019-12-20T15:19:03Z

packages/block-library/src/index.js

@@ -146,6 +148,12 @@ export const registerCoreBlocks = () => {
 		video,
 	].forEach( registerBlock );

+	// This line is just for testing
+	registerBlockCollection( 'core', {
+		title: 'Core',


As this seems ready to land, this test collection should be removed before we merge

scruffian · 2019-12-20T16:34:41Z

@draganescu thanks, done :)

youknowriad · 2019-12-23T07:32:49Z

docs/designers-developers/developers/block-api/block-registration.md

+
+Blocks can be added to collections, grouping together all blocks from the same origin
+
+`registerBlockCollection` takes three parameters `namespace`, `title` and `icon`.


I think the wording is incorrect since it's in fact two arguments.

youknowriad

Thanks for your work here, this is looking good. Ideally, we add an e2e test (plugin test) to validate this API. It could also be done as a follow-up.

youknowriad · 2019-12-23T07:35:31Z

(Let me know when it's rebased... so I can merge)

aduth · 2020-01-02T13:26:41Z

packages/blocks/src/api/registration.js

+ * Registers a new block collection to group blocks in the same namespace in the inserter.
+ *
+ * @param {string} namespace      The namespace to group blocks by in the inserter; corresponds to the block namespace
+ * @param {Object} title, icon    The title to show in the inserter, The icon to show in the inserter


This comma separation is not a valid syntax for JSDoc.

aduth · 2020-01-02T13:27:48Z

packages/blocks/src/store/selectors.js

+ *
+ * @param {Object} state Data state.
+ *
+ * @return {Array} Collections list.


Based on the state shape, I don't think this returns an array. Should it be returning an array though? That seems like what I might expect to receive as a consumer.

youknowriad · 2020-01-06T08:39:07Z

Would you mind a rebase here so we can consider merging it?

scruffian · 2020-01-06T12:49:48Z

@youknowriad I rebased this and fixed the incorrect docs. Thanks!

youknowriad · 2020-01-07T08:25:03Z

Thanks for your work here @scruffian

aduth · 2020-05-11T20:20:54Z

How does one test this? Is there any coverage in end-to-end tests?

aduth · 2020-05-11T20:22:09Z

Should a collection item search result be counted in the announced message?

Edit: I guess technically there are only two options present, though it's a bit more confusing in how there are four buttons for those two options.

aduth · 2020-05-11T20:31:35Z

Should reusable blocks be shown before or after block collections in the inserter?

aduth · 2020-05-11T20:52:10Z

Should a collection item search result be counted in the announced message?

Related: #22279

mtias · 2020-05-12T10:09:19Z

These collections are not meant to be shown as regular categories, so they should not show up in searches as one:

scruffian requested review from ajitbohra, chrisvanpatten, ellatrix, gziolo, jorgefilipecosta, mkaz, Soean, talldan and youknowriad as code owners September 26, 2019 13:37

gziolo added First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository [Feature] Block API API that allows to express the block paradigm. labels Sep 26, 2019

gziolo reviewed Sep 26, 2019

View reviewed changes

gziolo reviewed Oct 7, 2019

View reviewed changes

gziolo requested a review from mtias October 7, 2019 10:37

gziolo added Needs Technical Feedback Needs testing from a developer perspective. [Type] Technical Prototype Offers a technical exploration into an idea as an example of what's possible labels Oct 7, 2019

youknowriad reviewed Oct 7, 2019

View reviewed changes

youknowriad added the Needs Dev Note Requires a developer note for a major WordPress release cycle label Oct 7, 2019

gziolo reviewed Oct 25, 2019

View reviewed changes

gziolo assigned scruffian Oct 25, 2019

gziolo removed Needs Technical Feedback Needs testing from a developer perspective. [Type] Technical Prototype Offers a technical exploration into an idea as an example of what's possible labels Oct 25, 2019

scruffian force-pushed the add/block-collections branch from c1c94f8 to 966bf5a Compare November 26, 2019 17:53

haszari mentioned this pull request Nov 26, 2019

Improve discovery of Woo Blocks and their purpose via the block inserter. woocommerce/woocommerce-blocks#1265

Closed

scruffian force-pushed the add/block-collections branch from d4df845 to 7a1da8d Compare December 19, 2019 15:00

draganescu requested changes Dec 20, 2019

View reviewed changes

youknowriad reviewed Dec 23, 2019

View reviewed changes

youknowriad approved these changes Dec 23, 2019

View reviewed changes

aduth reviewed Jan 2, 2020

View reviewed changes

draganescu approved these changes Jan 6, 2020

View reviewed changes

scruffian added 3 commits January 6, 2020 12:38

rebase from master

ba27c0f

Adding block collections

40b9ce8

remove test collection

b3a7162

scruffian force-pushed the add/block-collections branch from 08c388c to b3a7162 Compare January 6, 2020 12:40

update the docs

408158b

youknowriad merged commit 0cb146d into WordPress:master Jan 7, 2020

scruffian deleted the add/block-collections branch January 7, 2020 10:26

ellatrix added this to the Gutenberg 7.3 milestone Jan 20, 2020

mapk mentioned this pull request Feb 4, 2020

Block Collection instead of category #16866

Closed

jorgefilipecosta mentioned this pull request Feb 12, 2020

Block Editor Dev Notes 5.4 #20185

Closed

23 tasks

ockham mentioned this pull request Feb 19, 2020

(wip) Extensions: organize blocks adding new categories Automattic/jetpack#14721

Closed

youknowriad removed the Needs Dev Note Requires a developer note for a major WordPress release cycle label Apr 8, 2020

aduth mentioned this pull request May 11, 2020

Block API: Allow block registration without category #22280

Merged

2 tasks

		@@ -1,4 +1,4 @@
		/* eslint no-console: [ 'error', { allow: [ 'error' ] } ] */
		/* eslint no-8: [ 'error', { allow: [ 'error' ] } ] */


		Blocks can be added to collections, grouping together all blocks from the same origin

		`registerBlockCollection` takes three parameters `namespace`, `title` and `icon`.

Add block collections #17609

Add block collections #17609

Conversation

scruffian commented Sep 26, 2019 • edited Loading

Description

How has this been tested?

Screenshots

Types of changes

Checklist:

gziolo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scruffian commented Sep 26, 2019

scruffian commented Sep 26, 2019

scruffian commented Sep 27, 2019

Choose a reason for hiding this comment

gziolo commented Oct 7, 2019

youknowriad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Oct 7, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scruffian commented Dec 4, 2019

scruffian commented Dec 19, 2019

draganescu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scruffian commented Dec 20, 2019

Choose a reason for hiding this comment

youknowriad left a comment

Choose a reason for hiding this comment

youknowriad commented Dec 23, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad commented Jan 6, 2020

scruffian commented Jan 6, 2020

youknowriad commented Jan 7, 2020

aduth commented May 11, 2020

aduth commented May 11, 2020 • edited Loading

aduth commented May 11, 2020

aduth commented May 11, 2020

mtias commented May 12, 2020

scruffian commented Sep 26, 2019 •

edited

Loading

aduth commented May 11, 2020 •

edited

Loading