Docs and API: clarify naming around block registration #842

mtias · 2017-05-19T13:13:03Z

There is some confusion around block instances as consumed in the editor and the registration API. We have two functions for getBlocks that return different things.

At the same time, we are keeping the block definition behind a getter like getBlockSettings where it is not immediately clear what the return value would be. (i.e. we return the save and edit render methods there.)

These are mainly relevant internally, but still important to be as clear as possible.

I propose we do one of the following:

/registration.js: getRegisteredBlock( name ) replaces getBlockSettings( slug ).
/registration.js: rename getBlocks to getRegisteredBlocks.

Or...

/registration.js: getBlockType( name ) replaces getBlockSettings( slug ).
/registration.js: rename getBlocks to getBlockTypes.

When retrieving settings and using them:

const blockType = getRegisteredBlock( name ) || getBlockType( name );
const EditBlock = blockType.edit;

aduth · 2017-05-19T19:41:51Z

blocks/api/factory.js

 	const blockSettings = getBlockSettings( blockType );

+	// Do we need this? What purpose does it have?


Let's create a separate issue for this. I think our current use-cases don't really need it as much as it seems they would.

aduth · 2017-05-19T19:44:55Z

I like registerBlock, getRegisteredBlock, and getRegisteredBlocks

More characters, but in my opinion best phrasing to indicate working with the "blueprint" of a block.

We'd probably want to be consistent with variable assignment too. const registeredBlock is a tad verbose but consistent with the function naming. blockType or blockSettings work well. block is a little non-descriptive for my liking.

ehg · 2017-05-22T21:30:00Z

More characters, but in my opinion best phrasing to indicate working with the "blueprint" of a block.

This is exactly how I've been thinking about the instance vs blueprint/prototype of a block. I prefer the explicit naming of a type vs. instance though, so would go for getBlockType. This feels a bit like React's element/component/component instance differences.

I really don't like blockSettings. It was confusing that these 'settings' contained functions, e.g. edit and save — which are verbs, but that's another story.

aduth · 2017-05-24T12:53:58Z

Yeah, "type" vocabulary is growing on me. I think I didn't like the distinction between registerBlock and getBlockTypes, but maybe if we were to name it registerBlockType ?

registerBlockType( 'core/text', {} );
const blockTypes = getBlockTypes();
const blockType = getBlockType( 'core/text' );

ehg · 2017-05-24T13:26:46Z

Yes. `registerBlockType` came up in another conversation. I'm all for that :)

…

On Wed, 24 May 2017, 13:54 Andrew Duthie, ***@***.***> wrote: Yeah, "type" vocabulary is growing on me. I think I didn't like the distinction between registerBlock and getBlockTypes, but maybe if we were to name it registerBlockType ? registerBlockType( 'core/text', {} );const blockTypes = getBlockTypes();const blockType = getBlockType( 'core/text' ); — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#842 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AANIIrFsyA2B0V88NJ8QQbFqKhjEhJQ6ks5r9ChngaJpZM4NggZR> .

aduth · 2017-05-31T02:03:48Z

blocks/api/parser.js

-		blockSettings = getBlockSettings( blockType );
+export function createBlockWithFallback( name, rawContent, attributes ) {
+	// Use type from block content, otherwise find unknown handler.
+	name = name || getUnknownTypeHandler();


Do we want to standardize on name vs. slug ?

I believe it to be clearer (slug usually not including slashes).

I think there's a few instances where we're already using slug.

Yes, I'm fine with cleaning up later.

ehg · 2017-05-31T08:55:22Z

blocks/README.md

@@ -146,7 +146,7 @@ Registers a new block-level control. Controls appear in a block's toolbar when i

 Inline controls for [`Editable`](#editable) elements are identical for every block and cannot be modified.

-### `wp.blocks.getBlockSettings( slug: string )`
+### `wp.blocks.getBlockType( slug: string )`

 Returns settings associated with a registered block.


settings? :)

settings? :)

I'm conflicted on this. What do we name the second argument to registerBlockType? Currently it's still settings. The "type" terminology doesn't apply as well. Maybe something more akin to "type definition", or configuration.

BE-Webdesign · 2017-05-31T14:36:42Z

blocks/api/factory.js

 * @param  {Object} attributes  Block attributes
 * @return {Object}             Block object
 */
-export function createBlock( blockType, attributes = {} ) {
-	const blockSettings = getBlockSettings( blockType );
+export function createBlock( blockName, attributes = {} ) {


I think blockName should remain blockType. Where you can interpret the value to be the ID of the blockType. (ignore this comment as I didn't read further down to realize that would be a catastrophe 😱 )

Actually maybe typeOfBlock then you can keep the new changes. That is what the string value is.

mtias · 2017-05-31T14:46:14Z

blocks/api/factory.js

-	const blockSettings = getBlockSettings( blockType );
+export function createBlock( blockName, attributes = {} ) {
+	// Get the type definition associated with a registered block.
+	const blockType = getBlockType( blockName );


The purpose of the PR is precisely to use blockType as the bespoke "prototype" or type description of the block, not the name, not the block instance.

Yup, you can disregard most of my comments as this is fine. It was somewhat confusing to me at first.

youknowriad

I tried testing everything. LGTM 👍

mtias · 2017-06-01T11:41:03Z

Thanks!

aduth · 2017-06-01T13:00:01Z

Nice one 👍

mtias force-pushed the update/docs-and-api branch from a76d104 to f057ac5 Compare May 19, 2017 13:42

aduth reviewed May 19, 2017

View reviewed changes

aduth mentioned this pull request May 24, 2017

Improve the block mover buttons accessibility #557

Closed

mtias force-pushed the update/docs-and-api branch from 9d3a410 to f60793a Compare May 30, 2017 17:36

mtias removed the [Status] In Progress Tracking issues with work in progress label May 30, 2017

aduth reviewed May 31, 2017

View reviewed changes

ehg reviewed May 31, 2017

View reviewed changes

mtias added the [Priority] High Used to indicate top priority items that need quick attention label May 31, 2017

BE-Webdesign reviewed May 31, 2017

View reviewed changes

mtias commented May 31, 2017

View reviewed changes

mtias and others added 12 commits June 1, 2017 12:17

Change api/registration getBlocks to getRegisteredBlocks.

e7ea7b4

Update inline documentation in blocks/api.

c86eebc

Expose getBlocks as getRegisteredBlocks.

41cb889

Use getBlockTypes.

9c81157

Switch to getBlockType / blockName pair.

9ef4372

Fix tests.

a2fe463

Rename (un)registerBlock as (un)registerBlockType

788743b

Convert more blockSettings to blockType

905ebaa

Rename PHP register_block to register_block_type

b2ad98b

Correct blockType to blockName

ae96acc

Update block Readme to refer to type.

f620983

Simplify blockName attribute.

11ac2a2

youknowriad force-pushed the update/docs-and-api branch from 073ca2b to 11ac2a2 Compare June 1, 2017 11:18

youknowriad approved these changes Jun 1, 2017

View reviewed changes

mtias merged commit bdabb3f into master Jun 1, 2017

mtias deleted the update/docs-and-api branch June 1, 2017 11:41

Verdinjoshua26 mentioned this pull request Nov 5, 2022

[Snyk] Fix for 1 vulnerabilities Verdinjoshua26/gutenberg#57

Open

This was referenced Dec 6, 2022

[Snyk] Security upgrade simple-git from 2.48.0 to 3.15.0 MaxMood96/gutenberg#80

Open

[Snyk] Security upgrade simple-git from 2.35.0 to 3.15.0 MaxMood96/gutenberg#81

Open

Verdinjoshua26 mentioned this pull request Dec 25, 2022

[Snyk] Fix for 1 vulnerabilities Verdinjoshua26/gutenberg#59

Open

Verdinjoshua26 mentioned this pull request Jun 20, 2023

[Snyk] Fix for 1 vulnerabilities Verdinjoshua26/gutenberg#71

Open

MaxMood96 mentioned this pull request Jan 13, 2024

[Snyk] Security upgrade simple-git from 3.5.0 to 3.15.0 MaxMood96/gutenberg#135

Open

naiba4 mentioned this pull request Apr 23, 2024

[Snyk] Security upgrade simple-git from 3.5.0 to 3.15.0 naiba4/gutenberg#56

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs and API: clarify naming around block registration #842

Docs and API: clarify naming around block registration #842

mtias commented May 19, 2017 •

edited

Loading

aduth May 19, 2017

aduth commented May 19, 2017

ehg commented May 22, 2017

aduth commented May 24, 2017

ehg commented May 24, 2017 via email

aduth May 31, 2017

mtias May 31, 2017

aduth May 31, 2017

mtias May 31, 2017

ehg May 31, 2017

aduth May 31, 2017

BE-Webdesign May 31, 2017 •

edited

Loading

BE-Webdesign May 31, 2017 •

edited

Loading

mtias May 31, 2017

BE-Webdesign May 31, 2017

youknowriad left a comment

mtias commented Jun 1, 2017

aduth commented Jun 1, 2017

		const blockSettings = getBlockSettings( blockType );

		// Do we need this? What purpose does it have?

Docs and API: clarify naming around block registration #842

Docs and API: clarify naming around block registration #842

Conversation

mtias commented May 19, 2017 • edited Loading

Choose a reason for hiding this comment

aduth commented May 19, 2017

ehg commented May 22, 2017

aduth commented May 24, 2017

ehg commented May 24, 2017 via email

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

BE-Webdesign May 31, 2017 • edited Loading

Choose a reason for hiding this comment

BE-Webdesign May 31, 2017 • edited Loading

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

mtias commented Jun 1, 2017

aduth commented Jun 1, 2017

mtias commented May 19, 2017 •

edited

Loading

BE-Webdesign May 31, 2017 •

edited

Loading

BE-Webdesign May 31, 2017 •

edited

Loading