Merge pull request #974 from WordPress/update/block-registration-func…

…tion-docs

Update block registration function docs and signature.

blocks/README.md

@@ -106,7 +106,7 @@ _[(Example in ES2015+, JSX)](https://gist.github.com/aduth/fb1cc9a2296110a62b963
 
 Let's briefly review a few items you might observe in the implementation:
 
-- When registering a new block, you must prefix its slug with a namespace for your plugin. This helps prevent conflicts when more than one plugin registers a block with the same slug.
+- When registering a new block, you must prefix its name with a namespace for your plugin. This helps prevent conflicts when more than one plugin registers a block with the same name.
 - You will use `createElement` to describe the structure of your block's markup. See the [Element documentation](../element/README.md) for more information.
 - Extracting `RandomImage` to a separate function allows us to reuse it in both the editor-specific interface and the published content.
 - The `edit` function should handle any case where an attribute is unset, as in the case of the block being newly inserted.
@@ -123,7 +123,7 @@ In the random image block above, we've given the `alt` attribute of the image a
 
 ### `wp.blocks.registerBlockType( name: string, typeDefinition: Object )`
 
-Registers a new block provided a unique slug and an object defining its behavior. Once registered, the block is made available as an option to any editor interface where blocks are implemented.
+Registers a new block provided a unique name and an object defining its behavior. Once registered, the block is made available as an option to any editor interface where blocks are implemented.
 
 - `title: string` - A human-readable [localized](https://codex.wordpress.org/I18n_for_WordPress_Developers#Handling_JavaScript_files) label for the block. Shown in the block picker.
 - `icon: string | WPElement | Function` - Slug of the [Dashicon](https://developer.wordpress.org/resource/dashicons/#awards) to be shown in the control's button, or an element (or function returning an element) if you choose to render your own SVG.
@@ -146,11 +146,11 @@ 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.getBlockType( slug: string )`
+### `wp.blocks.getBlockType( name: string )`
 
 Returns type definitions associated with a registered block.
 
-### `wp.blocks.getControlSettings( slug: string )`
+### `wp.blocks.getControlSettings( name: string )`
 
 Returns settings associated with a registered control.
 

blocks/api/parser.js

@@ -63,7 +63,7 @@ export function getBlockAttributes( blockType, rawContent, attributes ) {
 /**
  * Creates a block with fallback to the unknown type handler.
  *
- * @param  {?String} name       Block type slug
+ * @param  {?String} name       Block type name
  * @param  {String}  rawContent Raw block content
  * @param  {?Object} attributes Attributes obtained from block delimiters
  * @return {?Object}            An initialized block object (if possible)
@@ -102,8 +102,8 @@ export function createBlockWithFallback( name, rawContent, attributes ) {
  */
 export function parseWithGrammar( content ) {
 	return grammarParse( content ).reduce( ( memo, blockNode ) => {
-		const { blockType, rawContent, attrs } = blockNode;
-		const block = createBlockWithFallback( blockType, rawContent, attrs );
+		const { blockName, rawContent, attrs } = blockNode;
+		const block = createBlockWithFallback( blockName, rawContent, attrs );
 		if ( block ) {
 			memo.push( block );
 		}

blocks/api/post.pegjs

@@ -20,17 +20,17 @@ WP_Block
   / WP_Block_Html
 
 WP_Block_Void
-  = "<!--" __ "wp:" blockType:WP_Block_Type attrs:HTML_Attribute_List _? "/-->"
+  = "<!--" __ "wp:" blockName:WP_Block_Name attrs:HTML_Attribute_List _? "/-->"
   { return {
-    blockType: blockType,
+    blockName: blockName,
     attrs: attrs,
     rawContent: ''
   } }
 
 WP_Block_Balanced
-  = s:WP_Block_Start ts:(!WP_Block_End c:Any { return c })* e:WP_Block_End & { return s.blockType === e.blockType }
+  = s:WP_Block_Start ts:(!WP_Block_End c:Any { return c })* e:WP_Block_End & { return s.blockName === e.blockName }
   { return {
-    blockType: s.blockType,
+    blockName: s.blockName,
     attrs: s.attrs,
     rawContent: ts.join( '' ),
   } }
@@ -45,19 +45,19 @@ WP_Block_Html
   }
 
 WP_Block_Start
-  = "<!--" __ "wp:" blockType:WP_Block_Type attrs:HTML_Attribute_List _? "-->"
+  = "<!--" __ "wp:" blockName:WP_Block_Name attrs:HTML_Attribute_List _? "-->"
   { return {
-    blockType: blockType,
+    blockName: blockName,
     attrs: attrs
   } }
 
 WP_Block_End
-  = "<!--" __ "/wp:" blockType:WP_Block_Type __ "-->"
+  = "<!--" __ "/wp:" blockName:WP_Block_Name __ "-->"
   { return {
-    blockType: blockType
+    blockName: blockName
   } }
 
-WP_Block_Type
+WP_Block_Name
   = $(ASCII_Letter (ASCII_AlphaNumeric / "/" ASCII_AlphaNumeric)*)
 
 HTML_Attribute_List

blocks/api/registration.js

@@ -1,86 +1,86 @@
 /* eslint no-console: [ 'error', { allow: [ 'error' ] } ] */
 
 /**
- * Block settings keyed by block slug.
+ * Block settings keyed by block name.
  *
  * @type {Object}
  */
 const blocks = {};
 
 /**
- * Slug of block handling unknown types.
+ * Name of block handling unknown types.
  *
  * @type {?string}
  */
 let unknownTypeHandler;
 
 /**
- * Registers a new block provided a unique slug and an object defining its
+ * Registers a new block provided a unique name and an object defining its
  * behavior. Once registered, the block is made available as an option to any
  * editor interface where blocks are implemented.
  *
- * @param  {string}   slug     Block slug
+ * @param  {string}   name     Block name
  * @param  {Object}   settings Block settings
  * @return {?WPBlock}          The block, if it has been successfully
  *                             registered; otherwise `undefined`.
  */
-export function registerBlockType( slug, settings ) {
-	if ( typeof slug !== 'string' ) {
+export function registerBlockType( name, settings ) {
+	if ( typeof name !== 'string' ) {
 		console.error(
-			'Block slugs must be strings.'
+			'Block names must be strings.'
 		);
 		return;
 	}
-	if ( ! /^[a-z0-9-]+\/[a-z0-9-]+$/.test( slug ) ) {
+	if ( ! /^[a-z0-9-]+\/[a-z0-9-]+$/.test( name ) ) {
 		console.error(
-			'Block slugs must contain a namespace prefix. Example: my-plugin/my-custom-block'
+			'Block names must contain a namespace prefix. Example: my-plugin/my-custom-block'
 		);
 		return;
 	}
-	if ( blocks[ slug ] ) {
+	if ( blocks[ name ] ) {
 		console.error(
-			'Block "' + slug + '" is already registered.'
+			'Block "' + name + '" is already registered.'
 		);
 		return;
 	}
-	const block = Object.assign( { slug }, settings );
-	blocks[ slug ] = block;
+	const block = Object.assign( { name }, settings );
+	blocks[ name ] = block;
 	return block;
 }
 
 /**
  * Unregisters a block.
  *
- * @param  {string}   slug Block slug
+ * @param  {string}   name Block name
  * @return {?WPBlock}      The previous block value, if it has been
  *                         successfully unregistered; otherwise `undefined`.
  */
-export function unregisterBlockType( slug ) {
-	if ( ! blocks[ slug ] ) {
+export function unregisterBlockType( name ) {
+	if ( ! blocks[ name ] ) {
 		console.error(
-			'Block "' + slug + '" is not registered.'
+			'Block "' + name + '" is not registered.'
 		);
 		return;
 	}
-	const oldBlock = blocks[ slug ];
-	delete blocks[ slug ];
+	const oldBlock = blocks[ name ];
+	delete blocks[ name ];
 	return oldBlock;
 }
 
 /**
- * Assigns slug of block handling unknown block types.
+ * Assigns name of block handling unknown block types.
  *
- * @param {string} slug Block slug
+ * @param {string} name Block name
  */
-export function setUnknownTypeHandler( slug ) {
-	unknownTypeHandler = slug;
+export function setUnknownTypeHandler( name ) {
+	unknownTypeHandler = name;
 }
 
 /**
- * Retrieves slug of block handling unknown block types, or undefined if no
+ * Retrieves name of block handling unknown block types, or undefined if no
  * handler has been defined.
  *
- * @return {?string} Blog slug
+ * @return {?string} Blog name
  */
 export function getUnknownTypeHandler() {
 	return unknownTypeHandler;
@@ -89,11 +89,11 @@ export function getUnknownTypeHandler() {
 /**
  * Returns a registered block type.
  *
- * @param  {string}  slug Block slug
+ * @param  {string}  name Block name
  * @return {?Object}      Block type
  */
-export function getBlockType( slug ) {
-	return blocks[ slug ];
+export function getBlockType( name ) {
+	return blocks[ name ];
 }
 
 /**

blocks/api/test/factory.js

@@ -13,7 +13,7 @@ describe( 'block factory', () => {
 	afterEach( () => {
 		setUnknownTypeHandler( undefined );
 		getBlockTypes().forEach( ( block ) => {
-			unregisterBlockType( block.slug );
+			unregisterBlockType( block.name );
 		} );
 	} );
 

blocks/api/test/parser.js

@@ -24,7 +24,7 @@ describe( 'block parser', () => {
 	afterEach( () => {
 		setUnknownTypeHandler( undefined );
 		getBlockTypes().forEach( ( block ) => {
-			unregisterBlockType( block.slug );
+			unregisterBlockType( block.name );
 		} );
 	} );
 

blocks/api/test/registration.js

@@ -26,7 +26,7 @@ describe( 'blocks', () => {
 
 	afterEach( () => {
 		getBlockTypes().forEach( block => {
-			unregisterBlockType( block.slug );
+			unregisterBlockType( block.name );
 		} );
 		setUnknownTypeHandler( undefined );
 		console.error.restore();
@@ -35,26 +35,26 @@ describe( 'blocks', () => {
 	describe( 'registerBlockType()', () => {
 		it( 'should reject numbers', () => {
 			const block = registerBlockType( 999 );
-			expect( console.error ).to.have.been.calledWith( 'Block slugs must be strings.' );
+			expect( console.error ).to.have.been.calledWith( 'Block names must be strings.' );
 			expect( block ).to.be.undefined();
 		} );
 
 		it( 'should reject blocks without a namespace', () => {
 			const block = registerBlockType( 'doing-it-wrong' );
-			expect( console.error ).to.have.been.calledWith( 'Block slugs must contain a namespace prefix. Example: my-plugin/my-custom-block' );
+			expect( console.error ).to.have.been.calledWith( 'Block names must contain a namespace prefix. Example: my-plugin/my-custom-block' );
 			expect( block ).to.be.undefined();
 		} );
 
 		it( 'should reject blocks with invalid characters', () => {
 			const block = registerBlockType( 'still/_doing_it_wrong' );
-			expect( console.error ).to.have.been.calledWith( 'Block slugs must contain a namespace prefix. Example: my-plugin/my-custom-block' );
+			expect( console.error ).to.have.been.calledWith( 'Block names must contain a namespace prefix. Example: my-plugin/my-custom-block' );
 			expect( block ).to.be.undefined();
 		} );
 
 		it( 'should accept valid block names', () => {
 			const block = registerBlockType( 'my-plugin/fancy-block-4' );
 			expect( console.error ).to.not.have.been.called();
-			expect( block ).to.eql( { slug: 'my-plugin/fancy-block-4' } );
+			expect( block ).to.eql( { name: 'my-plugin/fancy-block-4' } );
 		} );
 
 		it( 'should prohibit registering the same block twice', () => {
@@ -69,7 +69,7 @@ describe( 'blocks', () => {
 			registerBlockType( 'core/test-block-with-settings', blockType );
 			blockType.mutated = true;
 			expect( getBlockType( 'core/test-block-with-settings' ) ).to.eql( {
-				slug: 'core/test-block-with-settings',
+				name: 'core/test-block-with-settings',
 				settingName: 'settingValue',
 			} );
 		} );
@@ -85,11 +85,11 @@ describe( 'blocks', () => {
 		it( 'should unregister existing blocks', () => {
 			registerBlockType( 'core/test-block' );
 			expect( getBlockTypes() ).to.eql( [
-				{ slug: 'core/test-block' },
+				{ name: 'core/test-block' },
 			] );
 			const oldBlock = unregisterBlockType( 'core/test-block' );
 			expect( console.error ).to.not.have.been.called();
-			expect( oldBlock ).to.eql( { slug: 'core/test-block' } );
+			expect( oldBlock ).to.eql( { name: 'core/test-block' } );
 			expect( getBlockTypes() ).to.eql( [] );
 		} );
 	} );
@@ -109,18 +109,18 @@ describe( 'blocks', () => {
 	} );
 
 	describe( 'getBlockType()', () => {
-		it( 'should return { slug } for blocks with no settings', () => {
+		it( 'should return { name } for blocks with no settings', () => {
 			registerBlockType( 'core/test-block' );
 			expect( getBlockType( 'core/test-block' ) ).to.eql( {
-				slug: 'core/test-block',
+				name: 'core/test-block',
 			} );
 		} );
 
 		it( 'should return all block type elements', () => {
 			const blockType = { settingName: 'settingValue' };
 			registerBlockType( 'core/test-block-with-settings', blockType );
 			expect( getBlockType( 'core/test-block-with-settings' ) ).to.eql( {
-				slug: 'core/test-block-with-settings',
+				name: 'core/test-block-with-settings',
 				settingName: 'settingValue',
 			} );
 		} );
@@ -136,8 +136,8 @@ describe( 'blocks', () => {
 			const blockType = { settingName: 'settingValue' };
 			registerBlockType( 'core/test-block-with-settings', blockType );
 			expect( getBlockTypes() ).to.eql( [
-				{ slug: 'core/test-block' },
-				{ slug: 'core/test-block-with-settings', settingName: 'settingValue' },
+				{ name: 'core/test-block' },
+				{ name: 'core/test-block-with-settings', settingName: 'settingValue' },
 			] );
 		} );
 	} );

blocks/test/full-content.js

@@ -134,12 +134,12 @@ describe( 'full post content fixture', () => {
 	it( 'should be present for each block', () => {
 		const errors = [];
 
-		getBlockTypes().map( block => block.slug ).forEach( slug => {
-			const slugToFilename = slug.replace( /\//g, '-' );
+		getBlockTypes().map( block => block.name ).forEach( name => {
+			const nameToFilename = name.replace( /\//g, '-' );
 			const foundFixtures = fileBasenames
 				.filter( basename => (
-					basename === slugToFilename ||
-					startsWith( basename, slugToFilename + '-' )
+					basename === nameToFilename ||
+					startsWith( basename, nameToFilename + '-' )
 				) )
 				.map( basename => {
 					const filename = basename + '.html';
@@ -153,20 +153,20 @@ describe( 'full post content fixture', () => {
 			if ( ! foundFixtures.length ) {
 				errors.push( format(
 					'Expected a fixture file called \'%s.html\' or \'%s-*.html\'.',
-					slugToFilename,
-					slugToFilename
+					nameToFilename,
+					nameToFilename
 				) );
 			}
 
 			foundFixtures.forEach( fixture => {
 				const delimiter = new RegExp(
-					'<!--\\s*wp:' + slug + '(\\s+|\\s*-->)'
+					'<!--\\s*wp:' + name + '(\\s+|\\s*-->)'
 				);
 				if ( ! delimiter.test( fixture.contents ) ) {
 					errors.push( format(
 						'Expected fixture file \'%s\' to test the \'%s\' block.',
 						fixture.filename,
-						slug
+						name
 					) );
 				}
 			} );