woocommerce/working-with-woocommerce-admin-pages.md at afee75f87110555e2647dd344efa9a37a1e73a69

8.4 KiB

Raw Blame History

post_title	menu_title	tags
Integrating admin pages into WooCommerce extensions	Integrating admin pages	how-to

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 PageController 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 PageController, 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 accepts an array of 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 Rect-powered page

To register a React-powered page, use the wc_admin_register_page() function. It accepts an array of 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-*. Note 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) - An array of parameters for registering items in WooCommerce Navigation. (see usage below)
- order - Order number for presentation.
- 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

if ( ! function_exists( 'YOUR_PREFIX_add_extension_register_page' ) ) {
  function YOUR_PREFIX_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', 'YOUR-TEXTDOMAIN' ),
        'parent'   => 'woocommerce',
        'path'     => '/example',
        'nav_args' => array(
            'order'  => 10,
            'parent' => 'woocommerce',
        ),
    ) );
  }
}
add_action( 'admin_menu', 'YOUR_PREFIX_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';
import { __ } from '@wordpress/i18n';
 
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', 'YOUR-TEXTDOMAIN' ) ],
        navArgs: {
            id: 'my-example-page',
            parentPath: '/other-example',
        },
    } );
 
    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 PageController in your call to wc_admin_register_page().

Pass the path to the parent page (the path value of the query arg for the parent page's url) as navArgs.parentPath to highlight that parent page's menu when this page is active.

8.4 KiB Raw Blame History