Commit 3a65ca9f184 for woocommerce
commit 3a65ca9f184616b02a5fd1d7847a4f06d9821772
Author: Brian Coords <bacoords@gmail.com>
Date: Tue Jul 21 10:01:14 2026 -0700
New settings intro guide and sidebar ordering for developer docs (#66567)
* initial commit of settings guide- pre edits
* Update settings docs overview and sidebar
diff --git a/docs/extensions/settings-and-config/README.md b/docs/extensions/settings-and-config/README.md
new file mode 100644
index 00000000000..8a9b0c64f4c
--- /dev/null
+++ b/docs/extensions/settings-and-config/README.md
@@ -0,0 +1,275 @@
+---
+post_title: 'Settings APIs and admin pages'
+sidebar_label: Overview
+sidebar_position: 0
+---
+
+# Settings APIs and admin pages
+
+Managing your settings, admin pages, and more is possible through the Settings APIs. The docs in this section cover what the Settings APIs and admin pages system offers in general. This guide goes further to map all of the various approaches you have available, some of the scenarios they cover, and the trade-offs of each approach.
+
+There are also code examples for your reference before you commit to an implementation path. However, reading through the approach you're interested in will give you greater scope to understand and apply the principles of each.
+
+## Approaches at a glance
+
+The Settings API and admin pages section has six approaches, outlined in the table. The four core concepts (Settings API, settings pages, settings tab sections, and admin pages) cover most settings and admin placement decisions, while the remaining approaches cover specialized integrations and navigation shortcuts.
+
+| Approach | Use when | Requires |
+| :---- | :---- | :---- |
+| [Settings API](/docs/extensions/settings-and-config/settings-api/) | Adding settings fields to an existing WooCommerce page, such as a payment gateway or shipping method | PHP |
+| [Settings pages](/docs/extensions/settings-and-config/extend-wc-settings-page/) | Your extension needs a full tab under **WooCommerce > Settings** with one or more sections | PHP |
+| [Settings tab sections](/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab/) | Your settings belong under an existing WooCommerce tab rather than a new page | PHP |
+| [Admin pages](/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages/) | Your extension needs a standalone page outside WooCommerce's settings structure | PHP or JavaScript |
+| [Integration settings](/docs/extensions/settings-and-config/implementing-settings/) | Your extension connects to a third-party service and needs a page under the Integrations tab | PHP |
+| [Store management links](/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links/) | Surfacing quick-access links on the WooCommerce home screen | JavaScript |
+
+## Settings API
+
+`WC_Settings_API` is the class that all WooCommerce settings build on, with payment gateways and shipping methods directly extending it. It's going to be the right tool when your extension adds settings fields to an existing WooCommerce context instead of creating a standalone settings page.
+
+There are three core responsibilities of this class:
+
+- Define fields in `init_form_fields()`.
+- Render them through `admin_options()`.
+- Hook `process_admin_options()` to the update hook that matches your context.
+
+For `process_admin_options()`, those contexts could be `woocommerce_update_options_payment_gateways` for a payment gateway, or `woocommerce_update_options_shipping_methods` for a shipping method.
+
+The API lets you control field placements without presupposing a location. However, this means it doesn't create a settings page for you, so you'll need to register that separately if needed. For extensions that fit within payment or shipping contexts, you are extending the same class that WooCommerce's own gateways use.
+
+```php
+class My_Extension_Settings extends WC_Settings_API {
+ public function __construct() {
+ $this->id = 'my_extension';
+ $this->init_form_fields();
+ $this->init_settings();
+ add_action(
+ 'woocommerce_update_options_' . $this->id,
+ array( $this, 'process_admin_options' )
+ );
+ }
+
+ public function init_form_fields() {
+ $this->form_fields = array(
+ 'enabled' => array(
+ 'title' => __( 'Enable', 'my-extension' ),
+ 'type' => 'checkbox',
+ 'default' => 'yes',
+ ),
+ );
+ }
+}
+```
+
+## Settings pages
+
+Use `WC_Settings_Page` when your extension needs a full tab under **WooCommerce > Settings**. A settings page class registers the tab, renders one or more sections, defines fields with WooCommerce's settings array format, and lets WooCommerce handle saving through the existing settings form.
+
+The main trade-off is navigation weight. If your extension only needs a few settings that clearly belong under an existing WooCommerce settings tab, add a section to that tab instead of creating a new top-level tab. If the extension needs an interface outside WooCommerce settings entirely, use admin page registration.
+
+```php
+final class My_Plugin_Settings_Page extends WC_Settings_Page {
+ public function __construct() {
+ $this->id = 'my_plugin';
+ $this->label = __( 'My plugin', 'my-plugin' );
+
+ parent::__construct();
+ }
+
+ protected function get_settings_for_default_section() {
+ return array(
+ array(
+ 'title' => __( 'My plugin settings', 'my-plugin' ),
+ 'type' => 'title',
+ 'id' => 'my_plugin_options',
+ ),
+ array(
+ 'title' => __( 'Enable feature', 'my-plugin' ),
+ 'id' => 'my_plugin_enabled',
+ 'type' => 'checkbox',
+ 'default' => 'no',
+ ),
+ array(
+ 'type' => 'sectionend',
+ 'id' => 'my_plugin_options',
+ ),
+ );
+ }
+}
+
+add_filter(
+ 'woocommerce_get_settings_pages',
+ function( $settings_pages ) {
+ $settings_pages[] = new My_Plugin_Settings_Page();
+ return $settings_pages;
+ }
+);
+```
+
+## Settings tab sections
+
+Rather than creating a whole new page, you can add a section beneath an existing WooCommerce settings tab using two filters:
+
+- `woocommerce_get_sections_{tab}` registers the section.
+- `woocommerce_get_settings_{tab}` supplies its fields.
+
+The `{tab}` portion of each filter corresponds to the tab you want to extend. For instance, `products` targets the **Products** tab, while `accounts` targets **Account and Privacy**.
+
+Placing settings under an existing tab keeps the admin area organized and means merchants find your extension's options in an understandable context. The limit is that linking to your section from documentation or onboarding flows requires a URL with both a tab and a section parameter rather than a page URL you control.
+
+```php
+add_filter(
+ 'woocommerce_get_sections_products',
+ function( $sections ) {
+ $sections['my_extension'] = __( 'My Extension', 'my-extension' );
+ return $sections;
+ }
+);
+
+add_filter(
+ 'woocommerce_get_settings_products',
+ function( $settings, $current_section ) {
+ if ( 'my_extension' === $current_section ) {
+ return array(
+ array(
+ 'title' => __( 'My Extension', 'my-extension' ),
+ 'type' => 'title',
+ 'id' => 'my_extension',
+ ),
+ array(
+ 'title' => __( 'Enable feature', 'my-extension' ),
+ 'type' => 'checkbox',
+ 'id' => 'my_extension_enabled',
+ ),
+ array(
+ 'type' => 'sectionend',
+ 'id' => 'my_extension',
+ ),
+ );
+ }
+
+ return $settings;
+ },
+ 10,
+ 2
+);
+```
+
+## Admin page registration
+
+When your extension needs a page outside WooCommerce's settings structure, you register it with the `PageController`. This attaches the WooCommerce Admin header and activity panel to the page and WooCommerce provides two registration paths:
+
+- `wc_admin_connect_page()` for PHP-powered pages.
+- `wc_admin_register_page()` for React-powered pages.
+
+PHP registration connects an existing admin page to the WooCommerce Admin shell. This will suit extensions that already render an interface with PHP. React registration creates a menu entry and renders a component you supply, which gives you a component-driven interface but requires a JavaScript build step.
+
+Both paths are for extensions with an interface that's too distinct to fit within WooCommerce's settings tabs. For example, this could be a reporting dashboard, a product import tool, or any page with its own layout.
+
+```php
+// PHP-powered page.
+wc_admin_connect_page(
+ array(
+ 'id' => 'my-extension-page',
+ 'screen_id' => 'my-extension-page',
+ 'title' => array( 'My Extension', 'Settings' ),
+ 'path' => add_query_arg( 'page', 'my-extension', 'admin.php' ),
+ )
+);
+```
+
+```jsx
+// React-powered page.
+import { addFilter } from '@wordpress/hooks';
+
+const MyPage = () => <h1>My Extension</h1>;
+
+addFilter( 'woocommerce_admin_pages_list', 'my-extension', ( pages ) => {
+ pages.push( {
+ container: MyPage,
+ path: '/my-extension',
+ breadcrumbs: [ 'My Extension' ],
+ } );
+
+ return pages;
+} );
+```
+
+## Integration settings
+
+`WC_Integration` extends `WC_Settings_API` and creates a settings page under **WooCommerce > Settings > Integrations**. It also handles data saving and sanitization for you. You should use it when your extension connects to an external service and a dedicated page under the **Integrations** tab is the right home for its settings.
+
+The main trade-off is placement: if your settings belong under an existing WooCommerce tab or on a standalone page, this is not the path. `WC_Integration` is great for fields such as API keys or toggle switches because you get saving and sanitization without writing that logic yourself.
+
+```php
+class My_Integration extends WC_Integration {
+ public function __construct() {
+ $this->id = 'my-integration';
+ $this->method_title = __( 'My Integration', 'my-integration' );
+ $this->method_description = __( 'Connect to My Service.', 'my-integration' );
+ $this->init_form_fields();
+ $this->init_settings();
+ add_action(
+ 'woocommerce_update_options_integration_' . $this->id,
+ array( $this, 'process_admin_options' )
+ );
+ }
+
+ public function init_form_fields() {
+ $this->form_fields = array(
+ 'api_key' => array(
+ 'title' => __( 'API Key', 'my-integration' ),
+ 'type' => 'text',
+ ),
+ );
+ }
+}
+
+add_filter(
+ 'woocommerce_integrations',
+ function( $integrations ) {
+ $integrations[] = 'My_Integration';
+ return $integrations;
+ }
+);
+```
+
+## Store management links
+
+The WooCommerce home screen includes a store management dashboard that displays quick-access links and statistics for merchants. You can add your own link there using the `woocommerce_admin_homescreen_quicklinks` JavaScript filter.
+
+However, two constraints apply:
+
+- Links must point to pages within WooCommerce as external URLs are not supported.
+- All extension-added links appear under a fixed **Extensions** category and custom categories are not available.
+
+You enqueue your script using `admin_enqueue_scripts`, with a dependency on `wp-hooks` and a priority higher than 15 to ensure it runs before the section renders.
+
+Note that this approach doesn't *configure* settings as its purpose is discoverability for merchants who use the WooCommerce home screen as a starting point for day-to-day tasks.
+
+```js
+import { megaphone } from '@wordpress/icons';
+import { addFilter } from '@wordpress/hooks';
+
+addFilter( 'woocommerce_admin_homescreen_quicklinks', 'my-extension', ( quickLinks ) => {
+ return [
+ ...quickLinks,
+ {
+ title: 'My Extension',
+ href: 'link/to/my-extension',
+ icon: megaphone,
+ },
+ ];
+} );
+```
+
+## Next steps
+
+With the trade-offs and code examples for each approach as a reference, you can work through the full documentation for the one your extension needs.
+
+1. [Settings API](/docs/extensions/settings-and-config/settings-api/). Core reference for the `WC_Settings_API` class.
+2. [Adding a settings page](/docs/extensions/settings-and-config/extend-wc-settings-page/). Creating a full tab under **WooCommerce > Settings**.
+3. [Adding a section to a settings tab](/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab/). Adding a section beneath an existing WooCommerce tab.
+4. [Working with WooCommerce admin pages](/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages/). Registering PHP and React admin pages.
+5. [Implementing settings with `WC_Integration`](/docs/extensions/settings-and-config/implementing-settings/). How to use the `WC_Integration` class for third-party service connections.
+6. [Adding store management links](/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links/). Navigation shortcuts on the WooCommerce home screen.
diff --git a/docs/extensions/settings-and-config/_category_.json b/docs/extensions/settings-and-config/_category_.json
index ea92b575a9b..2bb9d3288d6 100644
--- a/docs/extensions/settings-and-config/_category_.json
+++ b/docs/extensions/settings-and-config/_category_.json
@@ -1,4 +1,8 @@
{
"label": "Settings and config",
- "position": 3
+ "position": 3,
+ "link": {
+ "type": "doc",
+ "id": "README"
+ }
}
diff --git a/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab.md b/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab.md
index 31e1f73f32f..71194f76f3f 100644
--- a/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab.md
+++ b/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab.md
@@ -1,6 +1,7 @@
---
post_title: How to add a section to a settings tab
-sidebar_label: Add a section to a settings tab
+sidebar_label: Settings tab sections
+sidebar_position: 3
---
@@ -47,7 +48,7 @@ Make sure you change the **wcslider** parts to suit your extension's name / te
## How to Add Settings to a Section
-Now that you've got the tab, you need to filter the output of `woocommerce_get_sections_products` (or similar). You would add the settings like usual using the [**WooCommerce Settings API**](./settings-api.md), but check for the current section before adding the settings to the tab's settings array. For example, let's add the sample settings we discussed above to the new **wcslider** section we just created:
+Now that you've got the tab, you need to filter the output of `woocommerce_get_sections_products` (or similar). You would add the settings like usual using the [**WooCommerce Settings API**](/docs/extensions/settings-and-config/settings-api/), but check for the current section before adding the settings to the tab's settings array. For example, let's add the sample settings we discussed above to the new **wcslider** section we just created:
```php
/**
@@ -138,4 +139,4 @@ You would now just use your newly created settings like you would any other Word
## Conclusion
-When creating an extension for WooCommerce, think about where your settings belong before you create them. The key to building a useful product is making it easy to use for the end user, so appropriate setting placement is crucially important. For more specific information on adding settings to WooCommerce, check out the [**Settings API documentation**](https://github.com/woocommerce/woocommerce/blob/trunk/docs/extension-development/settings-api.md).
+When creating an extension for WooCommerce, think about where your settings belong before you create them. The key to building a useful product is making it easy to use for the end user, so appropriate setting placement is crucially important. For more specific information on adding settings to WooCommerce, check out the [**Settings API documentation**](/docs/extensions/settings-and-config/settings-api/).
diff --git a/docs/extensions/settings-and-config/extend-wc-settings-page.md b/docs/extensions/settings-and-config/extend-wc-settings-page.md
index 0150c020450..fed8df1a205 100644
--- a/docs/extensions/settings-and-config/extend-wc-settings-page.md
+++ b/docs/extensions/settings-and-config/extend-wc-settings-page.md
@@ -1,6 +1,6 @@
---
post_title: How to add a settings page
-sidebar_label: Add a settings page
+sidebar_label: Settings pages
sidebar_position: 2
---
diff --git a/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links.md b/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links.md
index da29f417731..48f80035917 100644
--- a/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links.md
+++ b/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links.md
@@ -1,6 +1,7 @@
---
post_title: How to add store management links
-sidebar_label: Add store management links
+sidebar_label: Store management links
+sidebar_position: 6
---
diff --git a/docs/extensions/settings-and-config/implementing-settings.md b/docs/extensions/settings-and-config/implementing-settings.md
index 52e1dfb61a2..e5033653e89 100644
--- a/docs/extensions/settings-and-config/implementing-settings.md
+++ b/docs/extensions/settings-and-config/implementing-settings.md
@@ -1,11 +1,11 @@
---
-post_title: Creating custom settings for WooCommerce extensions
-sidebar_label: Creating custom settings
-sidebar_position: 1
+post_title: Creating custom settings for WooCommerce integrations
+sidebar_label: Integration settings
+sidebar_position: 5
---
-# Creating custom settings for WooCommerce extensions
+# Creating custom settings for WooCommerce integrations
If you're customizing WooCommerce or adding your own functionality to it you'll probably need a settings page of some sort. One of the easiest ways to create a settings page is by taking advantage of the [`WC_Integration` class](https://woocommerce.github.io/code-reference/classes/WC-Integration.html 'WC_Integration Class'). Using the Integration class will automatically create a new settings page under **WooCommerce > Settings > Integrations** and it will automatically save, and sanitize your data for you. We've created this tutorial so you can see how to create a new integration.
diff --git a/docs/extensions/settings-and-config/index.mdx b/docs/extensions/settings-and-config/index.mdx
deleted file mode 100644
index 8f3bed460d4..00000000000
--- a/docs/extensions/settings-and-config/index.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
----
-title: Settings and config
-sidebar_position: 0
-sidebar_class_name: category-index
----
-
-import DocCardList from '@theme/DocCardList';
-
-<DocCardList />
diff --git a/docs/extensions/settings-and-config/registering-settings-ui-components.md b/docs/extensions/settings-and-config/registering-settings-ui-components.md
index 09076d7d982..dfaf2abbc2a 100644
--- a/docs/extensions/settings-and-config/registering-settings-ui-components.md
+++ b/docs/extensions/settings-and-config/registering-settings-ui-components.md
@@ -1,7 +1,7 @@
---
post_title: Registering settings UI components
-sidebar_label: Settings UI components
-sidebar_position: 6
+sidebar_label: Register settings UI components
+sidebar_position: 8
---
# Registering settings UI components
diff --git a/docs/extensions/settings-and-config/settings-api.md b/docs/extensions/settings-and-config/settings-api.md
index cc6bd291835..a7a581d84ba 100644
--- a/docs/extensions/settings-and-config/settings-api.md
+++ b/docs/extensions/settings-and-config/settings-api.md
@@ -1,5 +1,7 @@
---
post_title: Settings API
+sidebar_label: Settings API
+sidebar_position: 1
---
# Settings API
diff --git a/docs/extensions/settings-and-config/settings-ui.md b/docs/extensions/settings-and-config/settings-ui.md
index f6e6c017cd2..bbc9108003d 100644
--- a/docs/extensions/settings-and-config/settings-ui.md
+++ b/docs/extensions/settings-and-config/settings-ui.md
@@ -1,7 +1,7 @@
---
post_title: Settings UI
sidebar_label: Settings UI
-sidebar_position: 5
+sidebar_position: 7
---
# Settings UI
diff --git a/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages.md b/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages.md
index 88b89ebec12..f23a62fa44d 100644
--- a/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages.md
+++ b/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages.md
@@ -1,6 +1,7 @@
---
post_title: Integrating admin pages into WooCommerce extensions
-sidebar_label: Integrating admin pages
+sidebar_label: Admin pages
+sidebar_position: 4
---
diff --git a/docs/extensions/settings-and-config/email-editor-integration.md b/docs/features/email/email-editor-integration.md
similarity index 100%
rename from docs/extensions/settings-and-config/email-editor-integration.md
rename to docs/features/email/email-editor-integration.md