apply_filters( ‘block_categories_all’, array[] $block_categories, WP_Block_Editor_Context $block_editor_context )

User Contributed Notes

1. Skip to note 7 content

   wpsuika 3 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

   Adding a new (custom) block category and show that category at the top

   // Adding a new (custom) block category and show that category at the top
   add_filter( 'block_categories_all', 'example_block_category', 10, 2);
   function example_block_category( $categories, $post ) {
   	
   	array_unshift( $categories, array(
   		'slug'	=> 'example',
   		'title' => 'Example'
   	) );
   
   	return $categories;
   }
2. Skip to note 8 content

   Helder Vilela 5 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   Adding a new (custom) block category.

   /**
    * Adding a new (custom) block category.
    *
    * @param   array $block_categories                         Array of categories for block types.
    * @param   WP_Block_Editor_Context $block_editor_context 	The current block editor context.
    */
   function wpdocs_add_new_block_category( $block_categories, $block_editor_context ) {
   	// You can add extra validation such as seeing which post type
   	// is used to only include categories in some post types.
   	// if ( in_array( $block_editor_context->post->post_type, ['post', 'my-post-type'] ) ) { ... }
   
   	return array_merge(
   		$block_categories,
   		[
   			[
   				'slug'  => 'my-block-category',
   				'title' => esc_html__( 'My Block Category', 'text-domain' ),
   				'icon'  => 'wordpress', // Slug of a WordPress Dashicon or custom SVG
   			],
   		]
   	);
   }
   
   add_filter( 'block_categories_all', 'wpdocs_add_new_block_category' );
3. Skip to note 9 content

   Michael Bourne 5 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   Just a note that in base version WP 5.8, $block_editor_context can be either an object or a string. If you are using this filter and type hinting your callback, this could be the cause of the errors you’re undoubtedly seeing.

   Using @heldervilela code above as an example, you may need to do this:

   /**
    * Adding a new (custom) block category.
    *
    * @param   array $block_categories                                Array of categories for block types.
    * @param   WP_Block_Editor_Context|string $block_editor_context   The current block editor context, or a string defining the context.
    */
   function wpdocs_add_new_block_category( $block_categories, $block_editor_context ) {
       // Check the context of this filter, return default if not in the post/page block editor.
       // Alternatively, use this check to add custom categories to only the customizer or widget screens.
       if ( ! ( $block_editor_context instanceof WP_Block_Editor_Context ) ) {
           return $block_categories;
       }
   
       // You can add extra validation such as seeing which post type
       // is used to only include categories in some post types.
       // if ( in_array( $block_editor_context->post->post_type, ['post', 'my-post-type'] ) ) { ... }
    
       return array_merge(
           $block_categories,
           [
               [
                   'slug'  => 'my-block-category',
                   'title' => esc_html__( 'My Block Category', 'text-domain' ),
                   'icon'  => 'wordpress', // Slug of a WordPress Dashicon or custom SVG
               ],
           ]
       );
   }
    
   add_filter( 'block_categories_all', 'wpdocs_add_new_block_category' );
4. Skip to note 10 content

   Ronald Huereca 5 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   This snippet allows you to add block categories on WP 5.8 and below.

   if ( version_compare( $GLOBALS['wp_version'], '5.8-alpha-1', '<' ) ) {
   	add_filter( 'block_categories', 'wpdocs_add_block_category', 10, 2 );
   } else {
   	add_filter( 'block_categories_all', 'wpdocs_add_block_category', 10, 2 );
   }
   
   /**
    * Adding a new (custom) block category.
    *
    * @param   array                   $block_categories       Array of categories for block types.
    * @param   WP_Block_Editor_Context $block_editor_context   The current block editor context.
    */
   function wpdocs_add_block_category( $block_categories, $block_editor_context ) {
   	return array_merge(
   		$block_categories,
   		array(
   			array(
   				'slug'  => 'block-slug',
   				'title' => __( 'Block Category Title', 'text-domain' ),
   			),
   		)
   	);
   }

   • The old, deprecated block_categories filter passes a WP_Post instance as 2nd argument, the filter handler should check for that, as it currently always expects a `WP_Block_Editor_Context` instance of the new block_categories_all filter. The documentation recommends to check for the existence of the WP_Block_Editor_Context class as feature detection for the newer block_categories_all filter, see https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/#block_categories_all

     strarsis 4 years ago
5. Skip to note 11 content

   binsaifullah 4 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   // Boilerplate - a prefix: change it as per yours
   
     if ( ! function_exists( 'boilerplate_register_block_category' ) ) {
   
   	// wordpress version check and load filter for block category
   
   	if( version_compare( $GLOBALS['wp_version'], '5.7', '<' ) ) {
   		add_filter( 'block_categories', 'boilerplate_register_block_category', 10, 2 );
   	} else {
   		add_filter( 'block_categories_all', 'boilerplate_register_block_category', 10, 2 );
   	}
   
   	/**
   	 * Register custom category for blocks
   	 */
   
   	function boilerplate_register_block_category( $categories, $post ) {
   		return array_merge(
   			array(
   				array(
   					'slug'  => 'boilerplate',
   					'title' => __( 'Boilerplate', 'boilerplate' ),
   				),
   			),
   			$categories,
   		);
   	}
   
     }

   • The new block_categories_all filter passes as 2nd parameter a WP_Block_Editor_Context instead of a WP_Post instance. The post can be accessed as WP_Block_Editor_Context post property. Therefore your filter handler should check whether the 2nd parameter is a WP_Post or a WP_Block_Editor_Context so the post instance is correctly retrieved for further usage. The documentation recommends to check for the existence of the WP_Block_Editor_Context class as feature detection for the newer block_categories_all filter, see https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/#block_categories_all

     strarsis 4 years ago
6. Skip to note 12 content

   Cedric Moris Kelly 2 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   Declare a block category just once, or it will throw an error. It is useful to know if you split your code in several plugins.

   function my_block_category( $categories, $post ) {
           
       $category = array(
           'slug'  => 'my-category-slug',
           'title' => 'My category name,
       );
   
       if ( is_array( $categories ) ) {
           $existingSlugs = array_column( $categories, 'slug' );
   
           if ( is_array( $existingSlugs ) ) {
               if ( in_array( $category['slug'], $existingSlugs ) ) {
                   return $categories; // Bail early if category exists
               }
           }
       }
           
       array_unshift( $categories, $category ); // Add category on top of pile
   
       return $categories;
   }