Display heading levels dynamically in Heading Options when Heading block is selected #14689

igmoweb · 2019-03-28T17:32:34Z

Description

public_html/wp-content/plugins/gutenberg/packages/block-library/src/heading/edit.js now parses the heading selector choices into numbers and dynamically display them as selector options in sidebar and toolbar.
public_html/wp-content/plugins/gutenberg/packages/block-library/src/heading/heading-toolbar.js (HeadingToolbar component) now accepts another parameter, levelsRange, that allows passing a list of levels instead of min/max values. This would allow passing heading lists like H1, H3, H5... instead of the common H1, H2, H3, H4, H5.
If the levelsRange prop is preset, the minLevel and the maxLevel props will be ignored. I couldn't come up with another solution to keep backward compatibility for other developers that could be using this component in their own JS.

How has this been tested?

Create a new post and add a new heading block.
Use the following code to change the heading selector options:

wp.hooks.addFilter( 'blocks.registerBlockType', 'heading-blocks-settings', ( settings, blockName ) => {
	if ( blockName !== 'core/heading' ) {
		return settings;
	}

	const { attributes = {} } = settings;
	return {
		...settings,
		attributes: {
			...attributes,
			content: {
				...attributes.content,
				selector: 'h2,h3,h4',
			},
		},
	};
} );

And you should see just a subset of headings to choose:

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 · 2019-03-29T10:43:13Z

@WordPress/gutenberg-core that's a very interesting proposal. On one side, I like how it automates the handling of the heading levels. On the other hand, I don't think that updating the list of selectors is a good idea as it might invalidate Heading block in the previously stored blocks if they used removed hX tag names.

However, this PR gave me an idea that in addition to values of attributes we might want to pass down the schema definition to make it possible to use some metadata in the block. In this particular example, we could do the following change to attributes:

	level: {
		type: 'number',
		default: 2,
+ 		enum: [ 2, 3, 4 ],
	},

And use enum to filter out possible values of controls.

igmoweb · 2019-03-29T12:57:27Z

@gziolo Thanks for your response.

Whether updating the list of headings is a good idea or not, it's more up to a project specs. In our case, we need to prevent editors to use H1, H5 and H6 in their posts for consistency and SEO matters. I know that this change could invalidate the content of the block but that's something we're having in mind.

On the other hand, changing attributes by using blocks.registerBlockType filter is a reality and can be done easily so in my opinion, it would be up to the developer to know what's being done.

That said, I've updated the PR with your recommendation about the enum property so now the headings are displayed based on that property instead of the selectors inside content.

aduth

I like the implementation here in rendering based on the component's own enum value. The filter mechanic is maybe not the nicest experience for extending, but it seems like the best option currently available. It could probably do with some complementing documentation / tutorial for customizing the block options.

However, as I consider it more, it's worth highlighting that enum validation is not currently implemented in the browser (it is for server block registration). I fear that if this were to become implemented and values outside the limited enum range were to become rejected, we'd face the same issue of previous block content being marked as invalidated.

aduth · 2019-04-03T13:34:38Z