Tutorial: Create, Rename and Reorder Block Categories

[bph]

Discussed in #340

^{Originally posted by troychaplin November 15, 2024}
This snippet provides an example of a function to reorder and/or customize the title of the core or custom block categories. In this example the following modifications are happening:

• The title for Text is being updated
• A custom category is being placed after Text
• The embed blocks are being re-positioned below media

/**
 * Reorders the block categories in the WordPress editor.
 *
 * This function allows you to define a custom order for the block categories
 * in the WordPress editor, including the ability to set custom titles for
 * specific categories. Categories not included in the custom order will be
 * appended to the end of the list.
 *
 * @param array $categories The default block categories.
 * @return array The reordered block categories.
 */
function reorder_block_categories( $categories ) {
	// Define the new category order with custom titles where needed.
	$new_category_order = [
		[ 'slug' => 'text', 'title' => 'Text Elements' ],
		[ 'slug' => 'custom-category' ],
		[ 'slug' => 'media' ],
		[ 'slug' => 'embed' ],
		[ 'slug' => 'design', 'title' => 'Design & Layout' ],
	];

	// Get the default titles and slugs for the core block categories.
	$get_core_block_categories = array_column( $categories, 'title', 'slug' );

	// Check if the new category order has custom titles, fallback to default titles.
	foreach ( $new_category_order as &$new_category ) {
		$new_category['title'] = $new_category['title'] ?? $get_core_block_categories[ $new_category['slug'] ] ?? 'Untitled';
	}

	// Create an array of slugs from the new category order.
	$new_category_slugs = array_column( $new_category_order, 'slug' );

	// Filter out the remaining block categories that are not in the new order.
	$remaining_core_categories = array_filter( $categories, function ( $category ) use ( $new_category_slugs ) {
		return ! in_array( $category['slug'], $new_category_slugs, true );
	});

	// Merge the new category order with the remaining categories.
	return array_merge( $new_category_order, $remaining_core_categories );
}

add_filter( 'block_categories_all', 'example_block_category', 10, 2 );

[bph]

@troychaplin The Snippet format is not yet particular finalized as we just started working on it, but it's meant to cover a single purpose/task, people might want to do.
So if that's more elaborate you might consider it for a full tutorial, or split it up into multiple snippets.

Also cc: @justintadlock to assist.

[troychaplin]

Thanks @bph, I'm gonna work out the individual functions as I want a reorder function for another project but don't need the renaming. If @justintadlock would prefer them as individual functions I'll be prepared for that. Personally, I think it might be best as 2 functions. I could see reordering being desired more than renaming.

[troychaplin]

@justintadlock what's your opinion on one large function vs individual functions. I did a bit of work on these and ended up keeping the one function for my own personal use as it will register, reorder or rename all in one, it's just easier as an all-in-one.

[troychaplin]

The first draft of this snippet is ready for review -- https://docs.google.com/document/d/1g0ROKi6pUIScCVgMjI1j4TWV1S3BmQJxGOllEhxsaiI/edit?tab=t.0

[jonathanbossenger]

Hey @troychaplin, @bph asked me to review the snippet.

So, my first thought is that this would indeed make more sense as a developer blog post, mostly because it's a cool example of a real-world solution to a problem: adding categories, renaming existing categories, and then reordering them to meet client requirements.

Additionally, there's some fun PHP-related learning in there (altering array elements inside the foreach loop by assigning the $new_category value by reference, using the PHP array functions like array_column, array_filter, and array_merge) that might get missed by the first time reader of the snippet post. It feels almost a disservice not to dive into each of those things and explain them to the reader.

My suggestion would be to rework this as a developer blog post, with (more or less) the following rough outline:

1. Introduce the block_categories_all filter
2. Show how it can be used to add categories (this is the more common use case)
3. Then show how it can be used to rename category titles
4. Then show how it can also be used to reorder categories

Along the way, share info on all the other PHP-related things I mentioned above.

Alternatively, if you want to stick to snippets, I'd suggest turning this into three distinct snippets:

1. How to add a category
2. How to rename a category title
3. How to reorder the categories

Although I'd much prefer it if you went with the dev blog post 😁

That having been said, maybe you could do both? Start with the three snippets, and then from there create the blog post in the new year?

Last note: For the developer blog, we tend to be sticklers for following WordPress Coding Standards to the letter (even though some folks out there don't use/like them). To make life easier, I'll share the WPCS formatted version below.

add_filter( 'block_categories_all', 'modify_block_categories', 10, 2 );

**
 * Reorders the block categories in the WordPress editor.
 *
 * This function allows you to define a custom order for the block categories
 * in the WordPress editor, including the ability to set custom titles for
 * specific categories. Categories not included in the custom order will be
 * appended to the end of the list.
 *
 * @param array $categories The default block categories.
 * @return array The reordered block categories.
 */

function modify_block_categories( $categories ) {

	$new_category_order = array(
		array( 'slug' => 'media' ),
		array(
			'slug'  => 'custom-category',
			'title' => __( 'Custom Category', 'your-text-domain' ),
		),
		array(
			'slug'  => 'text',
			'title' => __( 'Text Elements', 'your-text-domain' ),
		),
		array( 'slug' => 'embed' ),
		array( 'slug' => 'design' ),
	);

	// Create an associative array of block categories with the slug as the key.
	$current_block_categories = array_column( $categories, 'title', 'slug' );

	// Check if the new category order has a title set, otherwise use the default title.
	foreach ( $new_category_order as &$new_category ) {
		$new_category['title'] = $new_category['title'] ?? $current_block_categories[ $new_category['slug'] ] ?? __( 'Untitled', 'your-text-domain' );
	}

	// Create an array of slugs from the new category order.
	$new_category_slugs = array_column( $new_category_order, 'slug' );

	// Filter out the remaining block categories that are not in the new order.
	$remaining_categories = array_filter(
		$categories,
		function ( $category ) use ( $new_category_slugs ) {
			return ! in_array( $category['slug'], $new_category_slugs, true );
		}
	);

	// Merge the new category order with the remaining categories.
	return array_merge( $new_category_order, $remaining_categories );
}

I also suggest two additional changes:

1. Rename the $get_block_categories array to $current_block_categories, just to make it easier to read what is stored in that array.
2. Consider moving the filter hook registration above the callback, as it makes the code easier to read.

[abhansnuk]

This would be a very valuable blog post as Jonathan has detailed. Could we still use the headings Jonathan suggests if it becomes a blog post as these are good searchable references.

I wonder from the discussion and looking at other snippets and a couple of blog posts, whether we have other content that could have snippets extracted easily from them too. This is wider than this current discussion, so will collate some examples and add it to a GitHub discussion if further exploration shows some value.

[troychaplin]

Thanks for the feedback @jonathanbossenger and @abhansnuk. Sounds like there would be an appetite for a larger article here. I would be happy to set aside some time to expand upon this.

@bph I know this was approved as a snippet, is there any process to approve this as a full article before I look at building this one out further?

[troychaplin]

@jonathanbossenger those standards get me every time. I do review and updated them in the end, I must have had my auto format turned on. I have to fix some settings in VSCode to easily switch between PSR2 and WPCS when needed.

[jonathanbossenger]

@troychaplin no worries, I have the same issue when switching between projects 😁

[bph]

I know this was approved as a snippet, is there any process to approve this as a full article before I look at building this one out further?

@troychaplin The topic was approved. Its status doesn't change because of the format changes. It is in the discretion of the writers and the reviewers to decide on the format if the topic is still the same. We just need to remove the "Snippet:" prefix in the issue title and remove the label

[troychaplin]

Thanks @bph, I thought that might be the case. Looking forward to diving into this on more very soon!

[troychaplin]

Moved back to In Progress until I rework the approach for this article, will request another first review when ready.