138 lines
5.5 KiB
Markdown
138 lines
5.5 KiB
Markdown
WooCommerce Admin Page Controller
|
|
=================================
|
|
|
|
Pages rendered with React and pages that include the WooCommmerce Admin header (containing the Activity Panel) need to be registered with the WooCommerce Admin Page Controller.
|
|
|
|
This is the API you will use to add your own React-powered page, or to include the WooCommerce Admin header on your plugin pages.
|
|
|
|
### Connecting a PHP-powered Page
|
|
|
|
To show the WooCommerce Admin header on existing PHP-powered admin pages (most plugin pages), use the `wc_admin_connect_page()` function.
|
|
|
|
Connecting pages uses five parameters to `wc_admin_connect_page()`:
|
|
|
|
* `id` - Identifies the page with the controller. Required.
|
|
* `parent` - Denotes the page as a child of `parent`. Used for breadcrumbs. Optional.
|
|
* `screen_id` - Corresponds to [`PageController::get_current_screen_id()`](../includes/page-controller/class-wc-admin-page-controller.php#L219) to determine the current page. Required.
|
|
* `title` - Page title. Used to build breadcrumbs. String or array of breadcrumb pieces. Required.
|
|
* `path` - Page path (relative). Used for linking breadcrumb pieces when this page is a `parent`. Optional.
|
|
|
|
#### Examples
|
|
|
|
```php
|
|
// WooCommerce > Settings > General (default tab).
|
|
wc_admin_connect_page(
|
|
array(
|
|
'id' => 'woocommerce-settings',
|
|
'screen_id' => 'woocommerce_page_wc-settings-general',
|
|
'title' => array(
|
|
__( 'Settings', 'woocommerce-admin' ),
|
|
__( 'General', 'woocommerce-admin' ),
|
|
),
|
|
'path' => add_query_arg( 'page', 'wc-settings', 'admin.php' ),
|
|
)
|
|
);
|
|
```
|
|
|
|
The `WooCommerce > Settings > General` example shows how to set up multiple breadcrumb pieces for a page. When building the breadcrumbs, WooCommerce will attach a link to `path` to the first piece in the `title` array. All subsequent pieces are plain text (not linked).
|
|
|
|
```php
|
|
// WooCommerce > Settings > Payments.
|
|
wc_admin_connect_page(
|
|
array(
|
|
'id' => 'woocommerce-settings-payments',
|
|
'parent' => 'woocommerce-settings',
|
|
'screen_id' => 'woocommerce_page_wc-settings-checkout',
|
|
'title' => __( 'Payments', 'woocommerce-admin' ),
|
|
'path' => add_query_arg(
|
|
array(
|
|
'page' => 'wc-settings',
|
|
'tab' => 'checkout',
|
|
),
|
|
'admin.php'
|
|
),
|
|
)
|
|
);
|
|
|
|
// WooCommerce > Orders.
|
|
wc_admin_connect_page(
|
|
array(
|
|
'id' => 'woocommerce-orders',
|
|
'screen_id' => 'edit-shop_order',
|
|
'title' => __( 'Orders', 'woocommerce-admin' ),
|
|
'path' => add_query_arg( 'post_type', 'shop_order', 'edit.php' ),
|
|
)
|
|
);
|
|
```
|
|
|
|
### Determining Screen ID
|
|
|
|
WooCommerce Admin implements it's own version of `get_current_screen()` to allow for more precise identification of admin pages.
|
|
|
|
Some screen ID 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
|
|
|
|
WooCommerce Admin can recognize WooCommerce pages that have both tabs and sub sections. For example, `woocommerce_page_wc-settings-products-inventory` is the `WooCommerce > Settings > Products > Inventory` page.
|
|
|
|
If your plugin adds new pages with tabs and sub sections, use the `wc_admin_pages_with_tabs` and `wc_admin_page_tab_sections` filters to have WooCommerce Admin generate accurate screen IDs for them.
|
|
|
|
You can also use the `wc_admin_current_screen_id` filter to make any changes necessary to the behavior.
|
|
|
|
### Registering a React-powered Page
|
|
|
|
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 `parent`.
|
|
|
|
Register pages with `wc_admin_register_page()` using these parameters:
|
|
|
|
* `id` - Identifies the page with the controller. Required.
|
|
* `parent` - Denotes the page as a child of `parent`. Used for breadcrumbs. Optional.
|
|
* `title` - Page title. Used to build breadcrumbs. String or array of breadcrumb pieces. Required.
|
|
* `path` - Page path (relative to `#wc-admin`). Used for identifying this page and for linking breadcrumb pieces when this page is a `parent`. Required.
|
|
* `capability` - User capability needed to access this page. Optional (defaults to `manage_options`).
|
|
* `icon` - Dashicons helper class or base64-encoded SVG. Optional.
|
|
* `position` - Menu item position for parent pages. Optional. See: `add_menu_page()`.
|
|
|
|
#### Example - Adding a New Analytics Report
|
|
|
|
Add our new report using the appropriate filter:
|
|
|
|
```javascript
|
|
import { addFilter } from '@wordpress/hooks';
|
|
|
|
addFilter( 'woocommerce_admin_reports_list', 'my-namespace', ( reports ) => {
|
|
reports.push( {
|
|
report: 'example',
|
|
title: __( 'Example', 'my-textdomain' ),
|
|
component: ExampleReportComponent,
|
|
} );
|
|
|
|
return reports;
|
|
} );
|
|
```
|
|
|
|
Register the report page with the controller:
|
|
|
|
```php
|
|
function add_report_menu_item( $report_pages ) {
|
|
$report_pages[] = array(
|
|
'id' => 'example-analytics-report',
|
|
'title' => __( 'Example', 'my-textdomain' ),
|
|
'parent' => 'woocommerce-analytics',
|
|
'path' => '/analytics/example',
|
|
);
|
|
|
|
return $report_pages;
|
|
}
|
|
add_filter( 'woocommerce_admin_report_menu_items', 'add_report_menu_item' );
|
|
```
|
|
|
|
### Further Reading
|
|
|
|
* Check out the [`PageController`](../includes/page-controller/class-wc-admin-page-controller.php) class.
|
|
* See how we're [connecting existing WooCommerce pages](../includes/page-controller/connect-existing-pages.php).
|
|
* See how we're [registering Analytics Reports](../includes/features/analytics/class-wc-admin-analytics.php#L75).
|