This article will go through the steps of creating a new plugin integration for Uncanny Automator. If you are creating new triggers or actions for an existing integration, please see Creating Actions and Creating Triggers.
If you don’t know what an integration is or aren’t familiar with the concepts of an integration code, name or icons, please read What Is An Integration for high-level definitions.
For an example of a complete working plugin that creates an integration, trigger, and action; please see https://github.com/UncannyOwl/Uncanny-Automator-Sample-Integration.
Contents
Summary
Every integration has two mandatory hooks.
-
add_action( 'uncanny_automator_add_integration', 'my_unique_add_integration_func', 10, 1 );
-
add_filter( 'uncanny_automator_maybe_add_integration', 'maybe_add_integration', 11, 2 );
These hooks will be used to define:
- if the integration should be loaded through a validation function
- the location of the icons and logos for the recipe creation UI
- the name of the integration
- the unique code associated with the integration code
Integration Code
The integration code uniquely identifies the integration. It should include uppercase letters only, be unique, and have a logical association with the plugin or service.
An integration code has several uses within an integration:
- Creates a unique filter to verify if this integration should be loaded. Ex if a certain plugin should be active, if a specific site setting is set, etc.
- Allows triggers and actions to be categorized under this integration.
If there is another integration with the same code, your integration will be skipped or will override the other integrations with the same code.
Ex:
- name “WordPress” code “WP”
- name “WooCommerce” code “WC”
If an integration already exists with the same integration code you are trying to add, then your integration may be skipped. The Uncanny Automator plugin has first priority to add integrations (before Pro).
To view a list of integrations that have been registered, visit a recipe creation page at http://www.example.com/wp-admin/post-new.php?post_type=uo-recipe, open the browser developer console (press F12), type in “UncannyAutomator.integrations” and press Enter.
Integration Name
The name of the integration is alphanumeric and should have no special characters. It would usually be the name the plugin or service that the integration is built for. The name can have a maximum of 14 characters.
Ex:
- plugin “Easy Digital Downloads” name “Easy Digital Downloads”
- service “Zapier” name “Zapier”
Integration Icons
There should be five versions of an icon created for your integration. You will need to know the URL for each. They should be stored inside the plugin or theme you are developing. They may be stored in the media library or externally, however that is not recommended.
The 5 icons are as follows:
- 16px by 16 px png icon with a transparent background
- 32px by 32 px png icon with a transparent background
- 64px by 64 px png icon with a transparent background
- 150px(max) by 62px(max) png logo with a transparent background
- 300px(max) by 125px(max) png logo with a transparent background
Adding Your Integration
Hook into integration registration
// Register the integration's name, icons, and code add_action( 'uncanny_automator_add_integration', 'my_unique_add_integration_func', 10 ,1 ); // Function names need to be unique
Register your integration
/** * Add integration data to Automator */ function my_unique_add_integration_func() { global $uncanny_automator; $uncanny_automator->register_integration( 'WCX', // Integration Code array( 'name' => 'WooCommerce Sample', // Integration Name 'icon_16' => plugins_url( 'integration-woocommerce-icon-16.png', __FILE__ ), 'icon_32' => plugins_url( 'integration-woocommerce-icon-32.png', __FILE__ ), 'icon_64' => plugins_url( 'integration-woocommerce-icon-64.png', __FILE__ ), 'logo' => plugins_url( 'integration-woocommerce.png', __FILE__ ), 'logo_retina' => plugins_url( 'integration-woocommerce@2x.png', __FILE__ ), ) ); }
Let’s break it down!
1. Let’s grab the Automator global object which stores all integrations, triggers, actions, and recipe data.
global $uncanny_automator;
2. Set up your data and use $uncanny_automator->register_integration() to register the integration.
$uncanny_automator->register_integration( ... );
Verifying when the integration should be loaded
Hook into integration validation
// This filter adds your integration to Automator and its associated triggers and actions, if it passes the validation function add_filter( 'uncanny_automator_maybe_add_integration', 'maybe_add_integration', 11, 2 );
Set up the validation function
/** * Check if the plugin we are adding an integration for is active based on integration code * * @param bool $status If the integration is already active or not * @param string $code The integration code * * @return bool $status */ function maybe_add_integration( $status, $code ) { if ( 'WCX' === $code ) { if ( class_exists( 'WooCommerce' ) ) { $status = true; } else { $status = false; } } return $status; }
Let’s break it down!
1. Let’s check if the $code being checked is for our integration code.
if ( 'WCX' === $code )
2. Check if the related plugin or service is active. If it’s a service like an external API that is always available then just return true.
if ( class_exists( 'WooCommerce' ) )
3. Set the status as true if the plugin or service is available and false if it is not.
if ( class_exists( 'WooCommerce' ) ) { $status = true; } else { $status = false; }
Complete Code
// Register the integration's name, icons, and code add_action( 'uncanny_automator_add_integration', 'my_unique_add_integration_func', 10 ,1 ); // Function names need to be unique /** * Add integration data to Automator */ function my_unique_add_integration_func() { global $uncanny_automator; $uncanny_automator->register_integration( 'WCX', // Integration Code array( 'name' => 'WooCommerce Sample', // Integration Name 'icon_16' => plugins_url( 'integration-woocommerce-icon-16.png', __FILE__ ), 'icon_32' => plugins_url( 'integration-woocommerce-icon-32.png', __FILE__ ), 'icon_64' => plugins_url( 'integration-woocommerce-icon-64.png', __FILE__ ), 'logo' => plugins_url( 'integration-woocommerce.png', __FILE__ ), 'logo_retina' => plugins_url( 'integration-woocommerce@2x.png', __FILE__ ), ) ); } // This filter adds your integration to Automator and its associated triggers and actions, if it passes the validation function add_filter( 'uncanny_automator_maybe_add_integration', 'maybe_add_integration', 11, 2 ); /** * Check if the plugin we are adding an integration for is active based on integration code * * @param bool $status If the integration is already active or not * @param string $code The integration code * * @return bool $status */ function maybe_add_integration( $status, $code ) { if ( 'WCX' === $code ) { if ( class_exists( 'WooCommerce' ) ) { $status = true; } else { $status = false; } } return $status; }
What’s next
After creating an integration, you may want to read Creating Triggers or Creating Actions.