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.
Note: This is a Developer level doc. If you are unfamiliar with code/templates and resolving potential conflicts, select a WooExpert or Developer for assistance. We are unable to provide support for customizations under our Support Policy.
Setting up the Integration
↑ Back to topCreating the Main Plugin File
↑ Back to topplugins_loaded
hook and check if the WC_Integration
class exists. If it doesn’t then the user most likely doesn’t have WooCommerce activated.
After you do that you need to register the integration. Load the integration file (we’ll get to this file in a minute). Use the woocommerce_integrations
filter to add a new integration to the array.
Creating the Integration Class
↑ Back to topWC_Integration
class so we want to make a child class. This way it inherits all of the existing methods and data.
You’ll need to set an id, a description, and a title for your integration. These will show up on the integration page.
You’ll also need to load the settings by calling:
$this->init_form_fields();
& $this->init_settings();
You’ll also need to save your options by calling the woocommerce_update_options_integration_{your method id}
hook.
Lastly you have to input some settings to save! I’ve included two dummy fields below but we’ll go more into fields in the next section.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<?php | |
/** | |
* Integration Demo Integration. | |
* | |
* @package WC_Integration_Demo_Integration | |
* @category Integration | |
* @author Patrick Rauland | |
*/ | |
if ( ! class_exists( 'WC_Integration_Demo_Integration' ) ) : | |
class WC_Integration_Demo_Integration extends WC_Integration { | |
/** | |
* Init and hook in the integration. | |
*/ | |
public function __construct() { | |
global $woocommerce; | |
$this->id = 'integration-demo'; | |
$this->method_title = __( 'Integration Demo', 'woocommerce-integration-demo' ); | |
$this->method_description = __( 'An integration demo to show you how easy it is to extend WooCommerce.', 'woocommerce-integration-demo' ); | |
// Load the settings. | |
$this->init_form_fields(); | |
$this->init_settings(); | |
// Define user set variables. | |
$this->api_key = $this->get_option( 'api_key' ); | |
$this->debug = $this->get_option( 'debug' ); | |
// Actions. | |
add_action( 'woocommerce_update_options_integration_' . $this->id, array( $this, 'process_admin_options' ) ); | |
} | |
/** | |
* Initialize integration settings form fields. | |
*/ | |
public function init_form_fields() { | |
$this->form_fields = array( | |
'api_key' => array( | |
'title' => __( 'API Key', 'woocommerce-integration-demo' ), | |
'type' => 'text', | |
'description' => __( 'Enter with your API Key. You can find this in "User Profile" drop-down (top right corner) > API Keys.', 'woocommerce-integration-demo' ), | |
'desc_tip' => true, | |
'default' => '' | |
), | |
'debug' => array( | |
'title' => __( 'Debug Log', 'woocommerce-integration-demo' ), | |
'type' => 'checkbox', | |
'label' => __( 'Enable logging', 'woocommerce-integration-demo' ), | |
'default' => 'no', | |
'description' => __( 'Log events such as API requests', 'woocommerce-integration-demo' ), | |
), | |
); | |
} | |
} | |
endif; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<?php | |
/** | |
* Plugin Name: WooCommerce Integration Demo | |
* Plugin URI: https://gist.github.com/BFTrick/091d55feaaef0c5341d8 | |
* Description: A plugin demonstrating how to add a new WooCommerce integration. | |
* Author: Patrick Rauland | |
* Author URI: http://speakinginbytes.com/ | |
* Version: 1.0 | |
* | |
* This program is free software: you can redistribute it and/or modify | |
* it under the terms of the GNU General Public License as published by | |
* the Free Software Foundation, either version 3 of the License, or | |
* (at your option) any later version. | |
* | |
* This program is distributed in the hope that it will be useful, | |
* but WITHOUT ANY WARRANTY; without even the implied warranty of | |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
* GNU General Public License for more details. | |
* | |
* You should have received a copy of the GNU General Public License | |
* along with this program. If not, see <http://www.gnu.org/licenses/>. | |
* | |
*/ | |
if ( ! class_exists( 'WC_Integration_Demo' ) ) : | |
class WC_Integration_Demo { | |
/** | |
* Construct the plugin. | |
*/ | |
public function __construct() { | |
add_action( 'plugins_loaded', array( $this, 'init' ) ); | |
} | |
/** | |
* Initialize the plugin. | |
*/ | |
public function init() { | |
// Checks if WooCommerce is installed. | |
if ( class_exists( 'WC_Integration' ) ) { | |
// Include our integration class. | |
include_once 'class-wc-integration-demo-integration.php'; | |
// Register the integration. | |
add_filter( 'woocommerce_integrations', array( $this, 'add_integration' ) ); | |
} else { | |
// throw an admin error if you like | |
} | |
} | |
/** | |
* Add a new integration to WooCommerce. | |
*/ | |
public function add_integration( $integrations ) { | |
$integrations[] = 'WC_Integration_Demo_Integration'; | |
return $integrations; | |
} | |
} | |
$WC_Integration_Demo = new WC_Integration_Demo( __FILE__ ); | |
endif; |
Creating Settings
↑ Back to topinit_form_fields()
method.
Types of Settings
↑ Back to top- text
- price
- decimal
- password
- textarea
- checkbox
- select
- multiselect
- title
- class
- css
- placeholder
- description
- default
- desc_tip
Creating Your Own Settings
↑ Back to top$this->form_fields
array, entering the kind of form control you want under type
.
You can override the default HTML for your form inputs by creating a method with a name of the format generate_{ type }_html
which outputs HTML markup. To specify how buttons are rendered, you’d add a method called generate_button_html
. For textareas, you’d add a generate_textarea_html
method, and so on. (Check out the generate_settings_html
method of the WC_Settings_API
class in the WooCommerce source code to see how WooCommerce uses this.)
The below example creates a button that goes to WooThemes.com.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/** | |
* Initialize integration settings form fields. | |
* | |
* @return void | |
*/ | |
public function init_form_fields() { | |
$this->form_fields = array( | |
// don't forget to put your other settings here | |
'customize_button' => array( | |
'title' => __( 'Customize!', 'woocommerce-integration-demo' ), | |
'type' => 'button', | |
'custom_attributes' => array( | |
'onclick' => "location.href='http://www.woothemes.com'", | |
), | |
'description' => __( 'Customize your settings by going to the integration site directly.', 'woocommerce-integration-demo' ), | |
'desc_tip' => true, | |
) | |
); | |
} | |
/** | |
* Generate Button HTML. | |
* | |
* @access public | |
* @param mixed $key | |
* @param mixed $data | |
* @since 1.0.0 | |
* @return string | |
*/ | |
public function generate_button_html( $key, $data ) { | |
$field = $this->plugin_id . $this->id . '_' . $key; | |
$defaults = array( | |
'class' => 'button-secondary', | |
'css' => '', | |
'custom_attributes' => array(), | |
'desc_tip' => false, | |
'description' => '', | |
'title' => '', | |
); | |
$data = wp_parse_args( $data, $defaults ); | |
ob_start(); | |
?> | |
<tr valign="top"> | |
<th scope="row" class="titledesc"> | |
<label for="<?php echo esc_attr( $field ); ?>"><?php echo wp_kses_post( $data['title'] ); ?></label> | |
<?php echo $this->get_tooltip_html( $data ); ?> | |
</th> | |
<td class="forminp"> | |
<fieldset> | |
<legend class="screen-reader-text"><span><?php echo wp_kses_post( $data['title'] ); ?></span></legend> | |
<button class="<?php echo esc_attr( $data['class'] ); ?>" type="button" name="<?php echo esc_attr( $field ); ?>" id="<?php echo esc_attr( $field ); ?>" style="<?php echo esc_attr( $data['css'] ); ?>" <?php echo $this->get_custom_attribute_html( $data ); ?>><?php echo wp_kses_post( $data['title'] ); ?></button> | |
<?php echo $this->get_description_html( $data ); ?> | |
</fieldset> | |
</td> | |
</tr> | |
<?php | |
return ob_get_clean(); | |
} |
Validating & Sanitizing Data
↑ Back to topSanitize
↑ Back to top
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/** | |
* Init and hook in the integration. | |
*/ | |
public function __construct() { | |
// do other constructor stuff first | |
// Filters. | |
add_filter( 'woocommerce_settings_api_sanitized_fields_' . $this->id, array( $this, 'sanitize_settings' ) ); | |
} | |
/** | |
* Sanitize our settings | |
*/ | |
public function sanitize_settings( $settings ) { | |
// We're just going to make the api key all upper case characters since that's how our imaginary API works | |
if ( isset( $settings ) && | |
isset( $settings['api_key'] ) ) { | |
$settings['api_key'] = strtoupper( $settings['api_key'] ); | |
} | |
return $settings; | |
} |
Validation
↑ Back to topvalidate_{setting key}_field
method for each field you want to validate. For example, with the api_key
field you need a validate_api_key_field()
method.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
public function validate_api_key_field( $key, $value ) { | |
if ( isset( $value ) && 20 < strlen( $value ) ) { | |
WC_Admin_Settings::add_error( esc_html__( 'Looks like you made a mistake with the API Key field. Make sure it isn't longer than 20 characters', 'woocommerce-integration-demo' ) ); | |
} | |
return $value; | |
} |