Exchange Custom Add-ons: Overview

(Difference between revisions)
Jump to: navigation, search
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
  
== Pre Requisites to creating an Exchange Add-on ==
+
== Pre Requisites to creating an Exchange Add-on == __NOEDITSECTION__
 
* The ability to create a WordPress plugin
 
* The ability to create a WordPress plugin
 
* Knowledge of the Exchange developers API
 
* Knowledge of the Exchange developers API
  
== Basics ==
+
== Basics == __NOEDITSECTION__
 
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.
 
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 ==
+
== Anatomy of an Exchange Add-on == __NOEDITSECTION__
 
All Exchange add-ons will need the following items:
 
All Exchange add-ons will need the following items:
 
* The main WordPress plugin file with standard WP plugin headers
 
* The main WordPress plugin file with standard WP plugin headers
Line 14: Line 14:
 
* Additional code located outside of the main WordPress plugin file.
 
* Additional code located outside of the main WordPress plugin file.
  
== Registering your Add-on with Exchange ==
+
== Registering your Add-on with Exchange == __NOEDITSECTION__
 
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 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 name
Line 27: Line 27:
 
<br />
 
<br />
  
=== The Add-ons Name ===
+
=== The Add-ons Name === __NOEDITSECTION__
 
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 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.
  
 
<br />
 
<br />
  
=== The Add-on's Description ===
+
=== The Add-on's Description === __NOEDITSECTION__
 
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.
 
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.
  
 
<br />
 
<br />
  
=== The Add-on's Author ===
+
=== The Add-on's Author === __NOEDITSECTION__
 
This is you or your company's name.
 
This is you or your company's name.
  
 
<br />
 
<br />
  
=== The Add-on Author's URL ===
+
=== The Add-on Author's URL === __NOEDITSECTION__
 
Where should people be directed when they want more information about the author of the Add-on?
 
Where should people be directed when they want more information about the author of the Add-on?
  
 
<br />
 
<br />
=== The Add-on's Icon ===
+
=== The Add-on's Icon === __NOEDITSECTION__
 
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.
 
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.
  
 
<br />
 
<br />
  
=== The Add-on's Init File ===
+
=== The Add-on's Init File === __NOEDITSECTION__
 
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, <strong>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.</strong> As a result, you will need to provide Exchange with the absolute path of your init file at registration.
 
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, <strong>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.</strong> As a result, you will need to provide Exchange with the absolute path of your init file at registration.
  
 
<br />
 
<br />
=== The Add-on's Category ===
+
=== The Add-on's Category === __NOEDITSECTION__
 
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:
 
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
 
* transaction-methods: For payment gateway add-ons
Line 65: Line 65:
 
<br />
 
<br />
  
=== The Add-on's Settings Callback ===
+
=== The Add-on's Settings Callback === __NOEDITSECTION__
 
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.
 
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 ==
+
== Putting it all together == __NOEDITSECTION__
  
 
This is the entirty of our main PHP file for the Stripe add-on. It's located in <code>/wp-content/plugins/exchange-addon-stripe/exchange-addon-stripe.php</code>
 
This is the entirty of our main PHP file for the Stripe add-on. It's located in <code>/wp-content/plugins/exchange-addon-stripe/exchange-addon-stripe.php</code>

Revision as of 18:00, July 23, 2013


Pre Requisites to creating an Exchange Add-on

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

Basics

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

<?php
/*
 * Plugin Name: iThemes Exchange - Stripe Add-on
 * Version: 0.1.0
 * Description: Adds the ability for users to checkout with Stripe.
 * Plugin URI: http://ithemes.com/exchange/stripe/
 * Author: iThemes
 * Author URI: http://ithemes.com
 * 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 addon
 *
 * @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'        => 'http://ithemes.com/exchange/stripe/',
        '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

Personal tools
Namespaces
Variants
Actions
iThemes Codex
Codex Navigation
Toolbox