Exchange Custom Add-ons: Overview

From iThemes Codex
Jump to: navigation, search

Video Introduction to the Exchange API

For a developer-centric introduction to iThemes Exchange, checkout out our video overview of the API

Pre Requisites to creating an Exchange Add-on

  • The ability to create a WordPress plugin
  • Knowledge of the Exchange developers API


Exchange is shipped with a handful of core add-ons that are located in the ithemes-exchange/core-addons folder. You may reference any of these add-ons when creating your own. The only difference between external add-ons (like the one you will create) and core add-ons is that external add-ons are wrapped within an WordPress plugin and must be enabled / disabled by activating or deactivating the WordPress plugin that contains it's code. While it is possible to register more than one Exchange add-on inside of a single WordPress plugin, we highly recommend a 1-to-1 relationship between plugins and add-ons.

Anatomy of an Exchange Add-on

All Exchange add-ons will need the following items:

  • The main WordPress plugin file with standard WP plugin headers
  • A call to it_exchange_register_addon() hooked to the it_exchange_register_addons action
  • Additional code located outside of the main WordPress plugin file.

Registering your Add-on with Exchange

The most important part of an Exchange add-on is the code used to register it with Exchange. This code contains several options that will provide the following information:

  • The add-on's name
  • The add-on's description
  • The add-on's author
  • The add-on author's URL
  • The add-on's icon
  • The add-on's init file
  • The add-on's category used by Exchange
  • The add-on's Settings callback

The Add-ons Name

The name for your Add-on should probably be the same as the WordPress plugin's name. The Add-on name will be displayed in the list of enabled add-ons on the Exchange add-ons page.

The Add-on's Description

This should be a short, one sentence description of what functionality your add-on provides to Exchange. It will be displayed in the list of enabled add-ons on the Exchange add-ons page.

The Add-on's Author

This is you or your company's name.

The Add-on Author's URL

Where should people be directed when they want more information about the author of the Add-on?

The Add-on's Icon

This is a 50x50 image displayed beside your add-on in the list of enabled add-ons on the Exchange add-ons page. We recommend using a png.

The Add-on's Init File

WordPress does not officially support dependent plugins and loads each plugins files as they come across them in the wp-content/plugins directory. This happens in an alphabetical manner and you cannot assume that Exchange or our required libraries have been loaded prior to your code. For this reason, it is essential that your add-on does not include any code other than the registration hook inside the main PHP file for the WordPress plugin. As a result, you will need to provide Exchange with the absolute path of your init file at registration.

The Add-on's Category

All Exchange add-on's belong to a category. These categories are used internally to determine when, where, and how the add-on is applied to Exchange. The current list of possible categories include:

  • transaction-methods: For payment gateway add-ons
  • product-type: For different product types.
  • admin: For add-ons related to admin functionality. eg: basic-reporting
  • coupons: For coupon related add-ons
  • taxonomy-type: For add-ons creating new taxonomies specifically for Exchange products

The Add-on's Settings Callback

Exchange will build your add-on's settings page for you and link to it from the list of enabled add-ons on the Exchange add-ons page. All you have to do is tell exchange what the callback method is for printing the contents of the page. If this function is callable, Exchange will handle the rest.

Putting it all together

This is the entirety of our main PHP file for the Stripe add-on. It's located in /wp-content/plugins/exchange-addon-stripe/exchange-addon-stripe.php Exchange will include /wp-content/plugins/exchange-addon-stripe/init.php for all the heavy lifting based on our file option.

 * Plugin Name: iThemes Exchange - Stripe Add-on
 * Version: 0.1.0
 * Description: Adds the ability for users to checkout with Stripe.
 * Plugin URI:
 * Author: iThemes
 * Author URI:
 * iThemes Package: exchange-addon-stripe
 * Installation:
 * 1. Download and unzip the latest release zip file.
 * 2. If you use the WordPress plugin uploader to install this plugin skip to step 4.
 * 3. Upload the entire plugin directory to your `/wp-content/plugins/` directory.
 * 4. Activate the plugin through the 'Plugins' menu in WordPress Administration.

 * This registers our plugin as a stripe add-on
 * @since 0.1.0
 * @return void
function it_exchange_register_stripe_addon() {
    $options = array(
        'name'              => __( 'Stripe', 'exchange-addon-stripe' ),
        'description'       => __( 'Adds the ability for users to checkout with Stripe.', 'exchange-addon-stripe' ),
        'author'            => 'iThemes',
        'author_url'        => '',
        'icon'              => ITUtility::get_url_from_file( dirname( __FILE__ ) . '/images/stripe50px.png' ),
        'file'              => dirname( __FILE__ ) . '/init.php',
        'category'          => 'transaction-methods',
        'supports'          => array( 'transaction_status' => true ),
        'settings-callback' => 'it_exchange_stripe_addon_settings_callback',    
    it_exchange_register_addon( 'stripe', $options );
add_action( 'it_exchange_register_addons', 'it_exchange_register_stripe_addon' );

← Back to Exchange Codex Home