Categories
Core wc-admin

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' ) ||
	! 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.

11 replies on “Call to action: Create access for your extension in the new Woo Navigation”

For custom developed extensions which have setting fields within WooCommerce > Settings currently, are there any guidelines around this such as whether we should also include a settings item within the extension’s own menu.

Liked by 1 person

As a plugin managed by Automattic it seems a bit strange in my opinion to incorporate all this functionality into WooCommerce as opposed to having the functionality in WP Core so any plugin or custom theme can create these navigation menus. If later it’s decided to implement a similar functionality into Core, it’s either going to requite plugin developers to update their WooCommerce addons (again) and/or keep fallback/duplicate code inside the WooCommerce plugin.

Liked by 1 person

Is there any improvement to the extensibility of Woocommerce Admin Analytics Reports with this release? I’m struggling to find documentation that explains what hooks and filters are available to extend the standard reports.

For example, it is currently possible to compare current sales with last year’s sales. In a similar way, I would like to write an extension which will allow current sales to be compared with a sales forecast. Where can I find documentation that describes the filters and actions available for extending reports in this way?

Like

I’m a bit confused about the instructions for trying this out. This blog post states:

“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.”

I’m running WooCommerce 5.0.0-beta.2,. which includes WooCommerce admin 1.9.0-rc.3. Should that be sufficient? If so, it’s not working for me – I don’t have “Features” under WooCommerce » Settings » Advanced?

Or do I need to specifically pull in WooCommerce Admin master to see this?

Thanks

Like

Is it possible to have multi-level nesting of menu items?

We would want all our plugins setting to be under our brand name, and then each plugin can have multiple settings/CPT.

Liked by 1 person

I am a little but confused about when this feature will be implemented into core.

For now we need to clone the wc admin from the github repo.

Does the WooCoomerce 5.0 will have this new menu or it will be added in future version?

PS: In RC release of WC 5.0 it is not added

Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.