Working with WooCommerce Admin Pages

Introduction

There are a number of ways to manage admin-area pages for your WooCommerce extension. You can use existing PHP pages or create new React-powered pages. Regardless of the approach you choose, you’ll need to register your page with the WooCommerce Admin Page Controller in order to display the WooCommerce Admin header and Activity Panel on your page.

Connecting a PHP-powered page to WooCommerce Admin

To register an existing PHP-powered admin page with the Page Controller, use the wc_admin_connect_page() function. For example:

wc_admin_connect_page(
    array(
        'id'        => 'woocommerce-settings',
        'screen_id' => 'woocommerce_page_wc-settings-general',
        'title'     => array('Settings', 'General'),
        'path'      => add_query_arg( 'page', 'wc-settings', 'admin.php' ),
    )
);

The wc_admin_connect_page() function takes up to five arguments, two of which are optional:

id – Required — This identifies the page with the controller.
parent – Optional — This value denotes the page as a child of a parent (using the parent’s ID) and is used for generating breadcrumbs.
screen_id – Required — This corresponds to PageController::get_current_screen_id(). It is used to determine the current page. (see note below)
title – Required — This corresponds to the page’s title and is used to build breadcrumbs. You can supply a String or an Array of breadcrumb pieces here.
path – Optional — This is the page’s relative path. Used for linking breadcrumb pieces when this page is a parent.

In the example above, you can see how to use an Array to construct breadcrumbs for your extension. WooCommerce will attach a link leading to the path value to the first piece in the title Array. All subsequent pieces are rendered as text and not linked.

A note about determining the screen ID

WooCommerce Admin uses its own version of get_current_screen() to allow for more precise identification of admin pages, which may have various tabs and subsections.

The format of this ID may vary depending on the structural elements present on the page. Some formats that the function will generate are:

{$current_screen->action}-{$current_screen->action}-tab-section
{$current_screen->action}-{$current_screen->action}-tab
{$current_screen->action}-{$current_screen->action} if no tab is present
{$current_screen->action} if no action or tab is present

If your extension adds new pages with tabs or subsections, be sure to use the wc_admin_pages_with_tabs and wc_admin_page_tab_sections filters to have WooCommerce generate accurate screen IDs for them.

You can also use the wc_admin_current_screen_id filter to make any changes necessary to the screen ID generation behavior.

Registering a React-powered page

To register a React-powered page, use the wc_admin_register_page() function. It accepts a number of different arguments:

id – Required — This identifies the page with the controller.
parent – Optional — This denotes the page as a child of parent (using the parent’s ID) and is used for generating breadcrumbs.
title – Required — This corresponds to the page’s title and is used to build breadcrumbs. You can supply a String or an Array of breadcrumb pieces here.
path – Required — This is the page’s path (relative to #wc-admin). It is used for identifying this page and for linking breadcrumb pieces when this page is a parent.
capability – Optional — User capability needed to access this page. The default value is manage_options.
icon – Optional — Use this to apply a Dashicons helper class or base64-encoded SVG. Include the entire dashicon class name, ie dashicons-*. Not that this won’t be included in WooCommerce Admin Navigation.
position – Optional — Menu item position for parent pages. See: add_menu_page().
nav_args – Optional — These are arguments for registering items in WooCommerce Navigation. (see usage below)
nav_args[ 'order' ] – Order number for presentation.
nav_args[ 'parent' ]– Menu for item to fall under. For example: woocommerce,woocommerce-settings or woocommerce-analytics. Categories added by an extension are available as well.

Registering a React-powered page is similar to connecting a PHP page, but with some key differences. Registering pages will automatically create WordPress menu items for them, with the appropriate hierarchy based on the value of parent.

Example: Adding a New WooCommerce Admin Page

function add_extension_register_page() {
    if ( ! function_exists( 'wc_admin_register_page' ) ) {
        return;
    }

    wc_admin_register_page( array(
        'id'       => 'my-example-page',
        'title'    => 'My Example Page',
        'parent'   => 'woocommerce',
        'path'     => '/example',
        'nav_args' => array(
            'order'  => 10,
            'parent' => 'woocommerce',
        ),
    ) );
}
add_action( 'admin_menu', 'add_extension_register_page' );

In the example above, we encapsulated our call to wc_admin_register_page() in a function that we have hooked to the admin_menu action. Once you have registered a page with the controller, you can supply a React component on the client side.

import { addFilter } from '@wordpress/hooks';

const MyExamplePage = () => <h1>My Example Extension</h1>;

addFilter( 'woocommerce_admin_pages_list', 'my-namespace', ( pages ) => {
    pages.push( {
        container: MyExamplePage,
        path: '/example',
        breadcrumbs: [ 'My Example Page' ],
        navArgs: {
            id: 'my-example-page',
        },
    } );

    return pages;
} );

Above, we’re creating a simple functional React component for the sake of demonstration, but a real-world extension would likely have a more complex nesting of components.

When supplying a component to the list of WooCommerce Admin Pages, it’s important to make sure that the value you specify for navArgs.id matches the id for the page you register with the Page Controller in your call to wc_admin_register_page().