Call to action: Create access for your extension in the new Woo Navigation

We’re excited to share a modern, streamlined WooCommerce Navigation that supports the commerce-first experience necessary to help store owners achieve success.

Read on to find out more about how you can stay ahead of the curve by integrating with — and hooking into — this updated navigation.

In the last five years, millions of store owners have used WooCommerce to help bring their businesses to life. WooCommerce has answered their needs by evolving from a WordPress plugin to a fully-fledged commerce platform, with an official Marketplace of world-class extensions. Through all these changes, our navigation has remained largely untouched – until now.

Selecting WooCommerce in the WordPress dashboard immediately takes store owners to a modern, uncluttered menu focused on core business functions: Store Analytics, Orders, Marketing, Products, Customers. In addition, we’ve also made Extensions a top-level menu item, so that store owners can find what they need – faster and without the distraction of site management tasks. 

Since the WordPress sidebar item registration no longer applies, extensions will need to add some code to be able to hook into navigation. Here’s where we need your help.

When will this new navigation be released?

The new WooCommerce navigation has been implemented in WooCommerce 4.9 on WordPress.com-hosted eCommerce plans as of January 2021. The Woo team is encouraging developers to integrate their extensions into the new navigation ahead of the optional beta release in early February. 

This will ensure the millions of Woo store owners can discover and access their favorite extensions when the new navigation becomes the default store experience.

How to hook into Navigation

Navigation includes core WooCommerce items, but extensions will need to register items for inclusion. The following sections describe the process and include example code; no JavaScript is necessary, but integration of React-based components is available. To get started, use a development version of WooCommerce Admin or WooCommerce Admin version 1.9 to turn on the Navigation by heading to WooCommerce > Settings > Advanced > Features and toggle the Navigation checkbox.

If you are writing an extension from scratch — or would like to add modern JavaScript tooling to an existing WooCommerce extension — consider using Create Extension, a command-line tool for quickly scaffolding an extension with WooCommerce and WordPress tooling built-in. 

All the code samples can be found WooCommerce Navigation Examples. Check it out if you’d like to see the following code in a working plugin.

Add a single Navigation item

Let’s begin by adding a PHP function that registers a WP Admin page on the admin_menu hook using the add_menu_page function.

function register_navigation_items() {
	function page_content(){
		echo '<div class="wrap"><h2>Testing</h2></div>';
	}

	add_menu_page( 'My Extension', 'My Extension', 'manage_woocommerce', 'my-extension-slug', 'page_content' );
}

add_action( 'admin_menu', 'register_navigation_items' );

Now that we have a page visible at /wp-admin/admin.php?page=my-extension-slug, the navigation item can be added.

Be sure to import the appropriate classes so their public methods are available.

use Automattic\WooCommerce\Admin\Features\Navigation\Menu;
use Automattic\WooCommerce\Admin\Features\Navigation\Screen;
use Automattic\WooCommerce\Admin\Features\Features;

Add a check to our function to make sure the classes are indeed available.

if (
	! method_exists( Screen::class, 'register_post_type' ) ||
	! method_exists( Menu::class, 'add_plugin_item' ) ||
	! method_exists( Menu::class, 'add_plugin_category' ) ||
	! class_exists( 'Features' ) ||
	! Features::is_enabled( 'navigation' ) 
) {
	return;
}

We can now register our item with Navigation. Be sure add a unique id for the Navigation item as no items can have the same id.

Menu::add_plugin_item(
	array(
		'id'         => 'my-extension',
		'title'      => __( 'My Extension', 'my-extension' ),
		'capability' => 'manage_woocommerce',
		'url'        => 'my-extension-slug',
	)
);

Visit /wp-admin/admin.php?page=my-extension-slug to see our item visible and functioning.

Add a Navigation category

We can also create a category to contain a set of navigation items.

Menu::add_plugin_category(
	array(
		'id'     => 'my-extension-category',
		'title'  => __( 'My Extension Category', 'my-extension' ),
		'parent' => 'woocommerce',
	)
);

Menu::add_plugin_item(
	array(
		'id'         => 'my-extension-cat-page',
		'title'      => __( 'My Extension Cat Page', 'my-extension' ),
		'capability' => 'manage_woocommerce',
		'url'        => 'my-extension-slug-cat-page',
		'parent'     => 'my-extension-category',
	)
);

Integrating registered Custom Post Types

If an extension creates a registered post type, those can be added to Navigation as well. First, let’s start by registering an example post type with properties that allow it to be visible.

register_post_type( 'my-post-type', array(
	'label'        => 'My Post Type',
	'public'       => true,
	'show_in_menu' => true,
) );

Register the post type screen with Navigation.

Screen::register_post_type( 'my-post-type' );

Use the helper method Menu::get_post_type_items to gather all the post types items available. Now register the “all” item in the same way previous Navigation items were added.

$post_type_items = Menu::get_post_type_items(
	my_post_type',
	array(
		'title'  => __( 'My Extension Post Type, 'my-extension' ),
		'parent' => 'my-extension-category',
	)
);

Menu::add_plugin_item( $post_type_items['all'] );

Navigation and modern Javascript applications

WooCommerce offers a way to easily create React-based pages by extending WooCommerce Admin. See documentation for more information and how to integrate extensions into WooCommerce Admin to easily add modern application pages with React.

A major benefit of a React app extending WooCommerce Admin is navigation without page refreshes between screens. WooCommerce Admin handles this for its own page and automatically for any of its extensions. 

It’s also possible to any custom components to a Navigation item. The following Javascript uses a SlotFill component to replace our previous example with a custom React component.

/**
 * External dependencies
 */
import { WooNavigationItem } from '@woocommerce/navigation';
import { registerPlugin } from '@wordpress/plugins';
import { Button } from '@wordpress/components';

const MyExtenstionNavItem = () => (
	<WooNavigationItem item="my-extension">
		<Button>Hello From JavaScript</Button>
	</WooNavigationItem>
);

registerPlugin( 'my-extension', { render: MyExtenstionNavItem } );

This can be useful for inserting any custom component to fully maximize a Navigation item. Adding route-aware links to avoid unnecessary page refreshes is a great use of this functionality. While hooking into WooCommerce Admin’s router so that navigating from any Analytics Report or Home Screen happens instantly is best achieved by extending WooCommerce Admin, a WooCommerce extension can also use its own router by taking advantage of this SlotFill.

Get started with the future of Woo

By working together, we’ll continue to help store owners move swiftly, save time, and focus on their business – when they win, we all win.
Got feedback or questions? Join us for developer office hours every Wednesday at 14:00 UTC in the WooCommerce Community Slack.

Many thanks to @claraclee for the help in writing this post.