From ba63366169bf8ce352460734a9974a12e66a9403 Mon Sep 17 00:00:00 2001
From: Brent MacKinnon <brent.mackinnon@a8c.com>
Date: Fri, 6 Oct 2023 15:06:22 -0300
Subject: [PATCH] Add settings-api.md

---
 docs/extension-development/settings-api.md | 110 +++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 docs/extension-development/settings-api.md

diff --git a/docs/extension-development/settings-api.md b/docs/extension-development/settings-api.md
new file mode 100644
index 00000000000..35f1dce1d72
--- /dev/null
+++ b/docs/extension-development/settings-api.md
@@ -0,0 +1,110 @@
+# Settings API
+
+The WooCommerce Settings API is used by extensions to display, save, and load settings. The best way to make use of the API in your extension is to create a class that extends the `WC_Settings_API` class:
+
+```php
+class My_Extension_Settings extends WC_Settings_API {
+	//
+}
+```
+
+## Defining form fields
+
+You can define your fields using a method called `init_form_fields` in your class constructor:
+
+```php
+$this->init_form_fields();
+```
+
+You must have your settings defined before you can load them. Setting definitions go in the `form_fields` array:
+
+```php
+/**
+ * Initialise gateway settings form fields.
+ */
+function init_form_fields() {
+	$this->form_fields = array(
+		'title'       => array(
+			'title'       => __( 'Title', 'your-text-domain' ),
+			'type'        => 'text',
+			'description' => __( 'This controls the title which the user sees during checkout.', 'your-text-domain' ),
+			'default'     => __( 'PayPal', 'your-text-domain' )
+		),
+		'description' => array(
+			'title'       => __( 'Description', 'your-text-domain' ),
+			'type'        => 'textarea',
+			'description' => __( 'This controls the description which the user sees during checkout.', 'your-text-domain' ),
+			'default'     => __( "Pay via PayPal; you can pay with your credit card if you don't have a PayPal account", 'your-text-domain' )
+		)
+	);
+} // End init_form_fields()
+```
+
+(Make sure your class initializes the `form_fields` property so that the "Creation of dynamic property" error is not thrown in PHP 8.2+)
+
+In the above example we define two settings, Title and Description. Title is a text box, whereas Description is a textarea. Notice how you can define a default value and a description for the setting itself.
+
+Setting definitions use the following format:
+
+```php
+'setting_name' => array(
+	'title'       => 'Title for your setting shown on the settings page',
+	'description' => 'Description for your setting shown on the settings page',
+	'type'        => 'text|password|textarea|checkbox|select|multiselect',
+	'default'     => 'Default value for the setting',
+	'class'       => 'Class for the input element',
+	'css'         => 'CSS rules added inline on the input element',
+	'label'       => 'Label', // For checkbox inputs only.
+	'options'     => array( // Array of options for select/multiselect inputs only.
+		'key' => 'value'
+	),
+)
+```
+
+## Displaying your settings
+
+Create a method called `admin_options` containing the following:
+
+```php
+function admin_options() {
+	?>
+	<h2><?php esc_html_e( 'Your plugin name', 'your-text-domain' ); ?></h2>
+	<table class="form-table">
+		<?php $this->generate_settings_html(); ?>
+	</table>
+	<?php
+}
+```
+
+This will output your settings in the correct format.
+
+## Saving your settings
+
+To have your settings save, add your class's `process_admin_options` method to the appropriate `_update_options_` hook. For example, payment gateways should use the payment gateway hook:
+
+```php
+add_action( 'woocommerce_update_options_payment_gateways', array( $this, 'process_admin_options' ) );
+```
+
+Other types of plugins have similar hooks:
+
+```php
+add_action( 'woocommerce_update_options_shipping_methods', array( $this, 'process_admin_options' ) );
+```
+
+## Loading your settings
+
+In the constructor you can load the settings you previously defined:
+
+```php
+// Load the settings.
+$this->init_settings();
+```
+
+After that you can load your settings from the settings API. The `init_settings` method above populates the settings variable for you:
+
+```php
+// Define user set variables
+$this->title       = $this->settings['title'];
+$this->description = $this->settings['description'];
+```