Implementing the WC Integration Class

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. 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

You’ll need at least two files to create an integration so you’ll need to create a directory.

Creating the Main Plugin File ↑ Back to top

Create your main plugin file to hook into the plugins_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 top

Now that we have the framework setup let’s actually implement this Integration class. There already is a WC_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.

Creating Settings ↑ Back to top

If you took a look through the last section you’ll see that we added two dummy settings using the init_form_fields() method.

Types of Settings ↑ Back to top

WooCommerce includes support for 8 types of settings.

  • text
  • price
  • decimal
  • password
  • textarea
  • checkbox
  • select
  • multiselect

And these settings have attributes which you can use. These affect the way the setting looks and behaves on the settings page. It doesn’t affect the setting itself. The attributes will manifest slightly differently depending on the setting type. A placeholder for example doesn’t work with checkboxes. To see exactly how they work you should look through the source code. Ex.

  • title
  • class
  • css
  • placeholder
  • description
  • default
  • desc_tip

Creating Your Own Settings ↑ Back to top

The built-in settings are great but you may need extra controls to create your settings page. That’s why we included some methods to do this for you.

First create a new setting. And under type enter in whatever new control you want.

Then create a new method to generate the HTML for that input. You can look through the source code for sample code. The below example creates a button that goes to WooThemes.com.

Validating & Sanitizing Data ↑ Back to top

To create the best user experience you’ll most likely want to validate and sanitize your data. The integration class already performs basic sanitization so that there’s no malicious code present but you could further sanitize by removing unused data. An example of sanitizing data would be integrating with a 3rd party service where all API keys are upper case. You could convert the API key to upper case which will make it a bit more clear for the user.

Sanitize ↑ Back to top

I’m going to show you how to sanitize data first because it’s a bit easier to understand. But the one thing you should keep in mind is that sanitizing happens after validation. So if something isn’t validated it won’t get to the sanitization step.

Validation ↑ Back to top

Validation isn’t always necessary but it’s nice to do. If your API keys are always 10 characters long and someone enters one that’s not 10 then you can print out an error message and prevent the user a lot of headache when they assumed they put it in correctly.

First set up a validate_{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.

A complete example ↑ Back to top

If you’ve been following along you should have a complete integration example. If you have any problems see our full integration demo.

 

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top