Settings API

The WooCommerce settings API is used by shipping methods and payment gateways to display, save and load options.

Defining form fields

↑ Back to top

You can define your fields using a method called init_form_fields in your constructor:

$this->init_form_fields();

You must have your settings defined before you can load them. Define your options like this, setting the form_fields array:

/**
 * Initialise Gateway Settings Form Fields
 */
 function init_form_fields() {
     $this->form_fields = array(
     'title' => array(
          'title' => __( 'Title', 'woocommerce' ),
          'type' => 'text',
          'description' => __( 'This controls the title which the user sees during checkout.', 'woocommerce' ),
          'default' => __( 'PayPal', 'woocommerce' )
          ),
     'description' => array(
          'title' => __( 'Description', 'woocommerce' ),
          'type' => 'textarea',
          'description' => __( 'This controls the description which the user sees during checkout.', 'woocommerce' ),
          'default' => __("Pay via PayPal; you can pay with your credit card if you don't have a PayPal account", 'woocommerce')
           )
     );
} // End init_form_fields()

In the above example we define 2 options – title and description. Title is a text box, whereas description is a textarea. Notice how you can set a default value and add a description for the option itself.

Add options in the following format:

'option_name' => array(
     'title' => 'Title for your option shown on the settings page',
     'description' => 'Description for your option shown on the settings page',
     'type' => 'text|password|textarea|checkbox|select|multiselect',
     'default' => 'Default value for the option',
     'class' => 'Class for the input',
     'css' => 'CSS rules added line to the input',
     'label' => 'Label', // checkbox only
     'options' => array(
          'key' => 'value'
     ) // array of options for select/multiselects only
)

Displaying admin options

↑ Back to top

Create a method called admin_options containing the following:

function admin_options() {
 ?>
 <h2><?php _e('You plugin name','woocommerce'); ?></h2>
 <table class="form-table">
 <?php $this->generate_settings_html(); ?>
 </table> <?php
 }

That will output your settings in the correct format.

Saving admin options

↑ Back to top

To have your options save, you simply have to hook in the process_admin_options function in your constructor. Payment gateways hook into the gateway save action:

add_action('woocommerce_update_options_payment_gateways', array(&$this, 'process_admin_options'));

Plugins have a simular hook:

add_action('woocommerce_update_options_shipping_methods', array(&$this, 'process_admin_options'));

Loading your settings

↑ Back to top

In the constructor you can load the settings you previously defined:

 // 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:

// Define user set variables
 $this->title = $this->settings['title'];
 $this->description = $this->settings['description'];