Last week I released a Google checkout add-on for Event Organiser Pro. I hope to see many more payment gateways available – and I hope that you will be a part of that!
With that in mind I wanted to take you through how any gateway can be added to Event Organiser in the form of a two-part tutorial. If you’re wondering where code in this tutorial should go, see this post. The example used throughout this two-parter is the Google checkout add-on, and you can see the code in its entirety here.
If you do create a plug-in which adds your favourite payment gateway to Event Organiser, you may want to release it as a free or commercial add-on. Please get in touch if you do!
Step 1: ‘Registering’ the payment gateway
This step is easy, we’re just telling the plug-in that the our payment gateway exists, this is so our plug-in can display it in the booking form
/**
* Register the gateway
* @param array $gateways Array of gateways
* @return Array of gateways with Google added
*/
function eventorganiser_gc_add_google_checkout( $gateways ){
$gateways['google'] = __( 'Google Checkout', 'eventorganiserp' );
return $gateways;
}
add_filter( 'eventorganiser_gateways', 'eventorganiser_gc_add_google_checkout' );
Tip: The order in which the gateways appear in $gateways determines their order on the booking forms
Now, registering the gateway like this automatically ‘enables’ it and automatically appears on the booking form. But we may want the ability to disable it, we can do so with the following filter
/**
* Remove gateways we do not want publically available
* @param array $gateways Array of gateways
* @return Array of gateways
*/
function eventorganiser_gc_set_google_checkout_status( $gateways ){
// We'll need to add stuff in later to conditionally
// remove the gateway depending on an option
if( isset( $gateways['google'] ) );
unset( $gateways['google'] );
return $gateways;
}
add_filter( 'eventorganiser_enabled_gateways', 'eventorganiser_gc_set_google_checkout_status' );
Now the gateway has disappeared again – later we’ll change that function to conditionally add or remove the gateway depending on an option set by the user.
Step 2: Adding the gateway options
Step 2a: Register the settings
First lets register our settings. We do this using the register_setting() function (see the Codex). The settings will appear under the ‘bookings’ tab, so the first argument should bet set to eventorganiser_bookings.
This doesn’t ‘do’ much but lets WordPress know about our settings.
/**
* Regsister the settings & settings section
*/
function eventorganiser_gc_register_settings( $tab_id ) {
register_setting( 'eventorganiser_bookings', 'eventorganiser_gc_settings', 'eventorganiser_gc_validate_settings' );
}
add_action( "eventorganiser_register_tab_bookings", 'eventorganiser_gc_register_settings', 20 );
Step 2b: Validating your options
In part 2a we used the third argument of register_settings() – this argument expects a callback function to validate the data received by the user when saving the options. I won’t go into detail here, but its important that you do validate the data received. The following doesn’t.
function eventorganiser_gc_validate_settings( $options ){
//Clean whatever is received!
return $options;
}
Step 2c: Adding our gateway section
In Event Organiser each gateway has its own section, so users can quickly navigate to the appropriate gateway and change its settings. So next we’ll add our own section.
To do this we will use the add_settings_section() function (see Codex). This function takes the following arguments:
- $id This is a string identifier for your section, and must be unique. Below we’ve called it eventorganiser_google_checkout_section. Remember this, we’ll need it later.
- $title – The title of the section
- $callback – A callback to display text at the top of the setting section. If you don’t want to display any text, just use set this to
__return_false. (__return_false()– a surprisingly useful function) - $page – The page identifier – in this case we are adding this section to the ‘eventorganiser_bookings’ page.
The code:
function eventorganiser_gc_add_settings(){
add_settings_section( 'eventorganiser_google_checkout_section', __( 'Google Checkout', 'eventorganiserp' ), '__return_false', 'eventorganiser_bookings' );
//We'll add some settings to this section next
}
add_action( "load-settings_page_event-settings", 'eventorganiser_gc_add_settings', 20, 0 );
Step 2d: Adding our options
We’ll now add to the above function to add a setting. There are three things to remember:
- The page we’re on is eventorganiser_bookings
- Our settings section is eventorganiser_google_checkout_section – see 2c
- Our options are called eventorganiser_gc_settings – see 2a
To add a setting to our section we’ll use the add_settings_field() function – see Codex. This accepts the following arguments:
- $id – A string identifier for the setting – we’ll never use this, but it needs to be unqiue.
- $title – A label for the setting (so our users know what it does )
- $callback – A callback which will product the mark-up for our setting.
- $page – The page to which we’re adding our setting
- $section – The section to which we’re adding our setting
- $args – An array of argument that will be passed to our callback function above.
Use the utility functions! Defining functions to produce the mark-up for form fields is a tedious task, so let Event Organiser do the hard work for you!
The name attribute of your options must begin with the name you set in 2a. In this example eventorganiser_gc_settings.
Here’s the same function from Step 2c, with two settings added:
function eventorganiser_gc_add_settings(){
add_settings_section( 'eventorganiser_google_checkout_section', __( 'Google Checkout', 'eventorganiserp' ), '__return_false', 'eventorganiser_bookings' );
/* Get options, and parse with default values */
$options = wp_parse_args( get_option( 'eventorganiser_gc_settings' ),
array(
'google_live_status' => 0,
'merchant_key' => '',
));
/* Addings a drop-down to swith the status of our payment gateway:
1 = Live, 0 = Sandbox, -1 = Disabled */
add_settings_field(
'google_live_status',
__( 'Live Switch', 'eventorganiserp' ),
'eventorganiser_select_field' ,
'eventorganiser_bookings',
'eventorganiser_google_checkout_section',
array(
'label_for'=>'google_live_status',
'name'=>'eventorganiser_gc_settings[google_live_status]',
'options'=>array(
'1'=>__( 'Live', 'eventorganiser' ),
'0'=>__( 'Sandbox Mode', 'eventorganiser' ),
'-1'=>__( 'Disable', 'eventorganiser' ),
),
'selected' => $options['google_live_status'],
)
);
/* Addings a text input for Google email */
add_settings_field(
'merchant_key',
__( 'Google Email', 'eventorganiserp' ),
'eventorganiser_text_field' ,
'eventorganiser_bookings',
'eventorganiser_google_checkout_section',
array(
'value'=>$options['merchant_key'],
'label_for'=> 'merchant_key',
'name'=>'eventorganiser_gc_settings[merchant_key]',
)
);
}
You should now have a working settings section.
Step 3 Enabling & Disabling
Before we go any further, let’s update the eventorganiser_gc_set_google_checkout_status() function we defined back in step 1. We want it to respect our ‘Google live status’ option
function eventorganiser_gc_set_google_checkout_status( $gateways ){
$options = get_option( 'eventorganiser_gc_settings' );
if( isset( $gateways['google'] ) && $options['google_live_status'] == -1 ){
unset( $gateways['google'] );
}
return $gateways;
}
Steps 4+
In the second part of this series we’ll cover how to actually implement the payment gateway!