Docs / / Hustle Providers API Doc

6. Hustle Providers API Doc

Written by Danae | Last updated: April 8, 2019

If you want to create your own provider for Hustle, we create three main classes to make it easier for you. You can extend those classes and add the necessary methods or properties. Then Hustle will show it as a new provider on the plugin UI. For your new provider core properties and global settings, you need to extend Hustle_Provider_Abstract class. For provider module settings you need to extend Hustle_Provider_Form_Settings_Abstract class. And lastly, you need to extend Hustle_Provider_Form_Hooks_Abstract class to specify the provider’s actions to be performed along with the plugin’s flow.

You can find all the necessary classes, properties and methods below and each of them has examples too.

General
To register your integration into Hustle’s framework
Class to extend and create your main integration’s class
Class to extend and create your integration’s settings class
Class to extend and create your integration’s hooks class
Functions to help your integration

6.1 Register Provider

Link to chapter 1
register()

Description

This method is used for registering your integration into Hustle’s framework. This is the first step toward integrating your script. No validation has been done until this point. Because of that, it’s possible that an integration registered with this method ends up not being included in Hustle if the requirements are not met.

The available integrations will show up on “Email collection services” from modules.

Usage

Hustle_Providers::get_instance()->register( $class_name );

Parameters

$class_name
String | Hustle_Provider_Abstract
The class name of the integration. Or an instance of the main integration class.

Return

Boolean.
TRUE => If registered successfully.
FALSE => If registration failed.

Registration will fail if:

  • The class name passed on $class_name does not exist.
  • The registered class is not an instance of “Hustle_Provider_Abstract” class.
  • The registered class does not have a “_slug” property.
  • The registered class does not have a “_version” property.
  • The registered class does not have a “_title” property.
  • The registered class does not have a “_class” property.
  • The provider’s method “check_is_compatible” returns false.
  • The registered class has the same slug as another registered integration.

See “Hustle_Provider_Abstract” class section for more information about the existing methods, properties, and requirements.

Example

 

6.2 Class: Hustle_Provider_Abstract

Link to chapter 2

Description

This class is the provider’s core and it’s required. What this class does:

-Defines the provider’s base properties such as the slug, title, version, etc.
-Sets the conditions for loading within Hustle, like the minimum PHP and Hustle versions, and customized checks.

-Handles the provider’s global settings.

Example

6.3 Properties: Provider

Link to chapter 3

Description

These are the useful properties for you within Hustle_Provider_Abstract class. Some of them must be defined on the integration in order to be properly loaded.

Properties to be defined

$_slug
String
Unique identifier of the integration. Make sure it’s unique, else it won’t be loaded or will carelessly override other providers with the same slug.
Required
Protected
$_version
String
Version number of the integration.
Required
Protected
$_class
String
Class name of the integration.
Required
Protected
$_title
String
Title of the integration that will be shown to users.
Required
Protected
$_min_hustle_version
String
Minimum version of Hustle so the provider works properly. The provider won’t be loaded if the current Hustle version is lower than this one.
Default: 3.0.5
Optional
Protected Static
$_icon_x2
String
This is the URL used for the “src” attribute of “img” tags for icons. This is shown in the providers listings. It’s expected to be retina ready.
Optional
Protected
$_logo_2x
String
This is the URL used for the “src” attribute of “img” tags for logos. This is shown in the provider settings modal. It’s expected to be retina ready.
Optional
Protected
$is_multi_on_form
Bool
Flag to allow multiple connections of your integration to a single module. See Zapier.
Optional
Protected
Default: false
$is_multi_on_global
Bool
Flag to allow multiple instances of your integration in the global settings to choose from when in the module’s settings. See Mailchimp.
Optional
Protected
Default: false
$_form_settings
String
Class name of integration’s settings as a string. Omit if form setting are not needed.
Optional
Protected
$_form_hooks
String
Class name of integration’s form hooks class as a string. Omit if not needed.
Optional
Protected
$_completion_options
Array
Array of options that should exist in the stored settings after these are completed. Checked to confirm if the integration is connected.
Optional
Protected
Default: [‘api_key’]

6.4 Methods to Define: Provider

Link to chapter 4
get_instance()

Description

This is a required method. It is used by Hustle to get an instance of your provider class.

Usage

Used by Hustle to get an instance of the provider.

Parameters

This method doesn’t have any parameters.

Return

Object. An instance of your provider class.

Example


check_is_compatible()

Description

Optional.
This method checks if the provider meets the requirements to be instantiated. If the provider is not compatible, it won’t be instantiated. Instantiating a not compatible provider may trigger PHP errors. By default, it will return false if:
– The installed PHP version is lower than the required by your integration.
– The installed Hustle version is lower than the required by your integration.

Usage

Used by Hustle when filtering out the providers that should not be loaded.
Override this method if you have another logic for checking if your integration is compatible.

Parameters

$class_name
String
Class Name of the integration.

Return

Boolean.

TRUE => If the integration is compatible. Everything is good, proceed with the load.

FALSE => If the integration is not compatible. Don’t proceed with the load. Don’t instantiate the integration.

Example


check_is_activable()

Description

Optional.
This method is called by is_activable() to verify if the integration can be activated. The final validation of the integration is done on this step. If it passes, it will be listed on Hustle.
By default, this method will return false if the method check_is_compatible() returns False. No other validation is done on this step. In the standard Hustle workflow, this method is not even called if check_is_compatible() returns False because that validation is done first and prevents the integration from being instantiated and included.

Usage

Used by Hustle when filtering out the providers that should not be loaded. Override it if there are other variables you would like to check so your integration runs properly, such as the existence of required third-party plugins, for example.

Parameters

It doesn’t have any parameters.

Return

TRUE => If the integration is activable.
FALSE=> If the integration is not activable.

If not overridden, this method will return false if the method check_is_compatible() returns false. No other validation is done here.

Example


is_form_settings_available()

Description

Optional.
This method is called to check if the integration has settings to be displayed. It returns false when the request is not made on the admin side, and it checks if the current array of settings is valid.

Usage

Used by Hustle to define whether your integration has a valid settings wizard to be displayed.
Override it if you want to do some extra checks to hide or show the provider’s module settings.

Parameters

It doesn’t have any parameters.

Return

TRUE => If form settings are available.
FALSE => If form settings are not available.

If not overridden, the method will return false if:
is_admin() returns false.
The property $_form_settings is null.
The class instantiated by $_form_settings class name is not an instance of Hustle_Provider_Form_Settings_Abstract.
The settings steps defined in the integration’s settings is not a valid array.
The number of steps defined in the integration’s settings is less than 1.

See “Hustle_Provider_Form_Settings_Abstract” class section for more information about the existing methods, properties, and requirements.

Example


settings_wizards()

Description

Optional.
Similar to “Husle_Provider_Form_Settings_Abstract::form_settings_wizaard()”, but for global settings. With this method, you will be able to display a form with settings for users to configure your integration in global settings. On these settings is where you allow users to save their API key, webhook URL, or anything you want to be accessible for your provider along with all the modules. This method is used by Hustle to get the settings from your integration to be displayed on each step and to get the values to be stored after submission.

Usage

Used by Hustle when getting the settings to be displayed and saving their values.
Override it if your integration has global configurations to set up.

Parameters

It doesn’t have any parameters.

Return

It must return an array. This array must contain one array for each settings step.
Each step must contain two key => value pairs.
One key must be named “callback”. Its value should be an array to be used as the first argument for call_user_func() function.
The other key must be named “is_completed”. Its value should be an array to be used as the first argument for call_user_func() function.
The array might contain the number of steps your integration requires.

Example

6.5 Methods to Use: Provider

Link to chapter 5
get_current_data()

Description

Helper. Get the current global data for integration. Receives an array with the name of the setting to retrieve and it’s a default value, and another array with the submitted data. If the setting is not in the submitted data, this function will retrieve it from the stored settings. The defaults will be used if the setting wasn’t found. Handles the stored settings for global multi-instances if the property $is_multi_on_global is set to “true”.

Usage

Use it to retrieve a merge of your provider’s stored global settings, with the submitted values, and defaults as a fallback.

Parameters

$default_data
Array
Associative array. Use the name of the setting to retrieve as the key, and the default value as its value.
$submitted_data
Array
Array with the submitted data.

Return

Associative array. The settings names will be the keys, and their stored value will be the value of the pair.

Example


get_settings_values()

Description

Get the stored global settings for this provider.

Usage

Use it to retrieve the stored settings of your provider.

Parameters

It doesn’t have any parameters.

Return

Associative array.

Example


get_setting()

Description

Helper. Get the requested global settings for this provider, given the setting name and the global instance ID if needed.
Uses “Hustle_Provider_Abstract::get_settings_values()”.

Usage

Use it to retrieve the global stored setting of your provider.

Parameters

$setting_name
String
The name of the setting to be retrieved.
$default
Mixed
The value to return if the setting wasn’t found. Default: false.
$global_multi_id
String
The ID of the global instance this setting belongs to. Default: false.

Return

Mixed.

Example


save_settings_values()

Description

Saves the given array as the provider’s global settings. If your provider allows global multi-instances, you can use the helper method “Hustle_Provider_Abstract::save_multi_settings_values()”.

Usage

Use it to save the given array as your provider’s global settings.

Parameters

$values
Array
The associative array with the values to be stored.

Return

There’s nothing to return.

Example


save_multi_settings_values()

Description

Helper. Saves the given array as the provider’s settings for the given global multi-instance ID.
Uses “Hustle_Provider_Abstract::save_settings_values()”.

Usage

Use it to save the given array as your provider’s settings for the given global multi-instance ID.

Parameters

$global_multi_id
String
The ID of the global instance to which these values belong to.
$values
Array
The associative array with the values to be stored.

Return

There’s nothing to return.

Example


is_multi_form_settings_complete()

Description

For providers supporting multi-instances on modules. Checks whether a module instance of your provider was successfully set up.

Usage

Used by Hustle to check if an instance of your provider was successfully configured.
Override it to set the condition that flags your provider’s instance as “completed”.

Parameters

$multi_id
String
The ID of the instance that’s being checked.
$settings
Array
Stored module settings of this instance of your provider.

Return

Boolean.

Example


settings_are_completed()

Description

Verify if the global instance of the provider has been successfully connected. It checks if the settings defined in “Hustle_Provider_Abstract::$_completion_options” are stored and aren’t empty.

Usage

Use it to check if your provider is globally connected.
Overwrite it if the validation you require is different than the default one.

Parameters

$multi_id
String
The ID of the global instance you want to verify. Leave empty if your integration doesn’t support multiple global instances. Default: ‘’.

Return

Boolean.

Example


get_global_multi_id()

Description

Helper. Return the submitted global_id if passed in the given array, or generates a new one if none was submitted.

Usage

Only for when your provider supports multiple global instances. Use it to get the global ID instance when displaying wizards.

Parameters

$submitted_data
Array
Array with the submitted data. It will include the global instance ID automatically if your provider supports it.

Return

String

Example

6.6 Class: Hustle_Provider_Form_Settings_Abstract

Link to chapter 6

Description

Extend this class to create the settings for your integration.

Example

6.7 Properties: Form Settings

Link to chapter 7

Description

Useful properties for your integration within Hustle_Provider_Form_Settings_Abstract class.

Properties to be used

$provider
Hustle_Provider_Abstract
The instance of the main class of your integration.
Protected
$module_id
Integer
The ID of the current module that’s making use of this class.
Protected
$addon_form_settings
Array
Stored settings at the moment of the class’ instantiation. Retrieved with Hustle_Provider_Form_Settings_Abstract::get_form_settings_values()
Protected

6.8 Methods to Define: Form Settings

Link to chapter 8
__construct()

Description

Optional

This method is used to initialize the integration’s settings. If overridden, call the parent constructor function. If your integration requires an external file that might not be compatible with the current PHP or Hustle version and might cause errors if included in those cases, this is a good place to include it.
Hustle will check if the current PHP and Hustle installations are compatible with your provider before instantiating it.

Usage

Used by Hustle when instantiating the class. Extend this method if you want to do anything during the instantiation. If you’re extending this method, make sure to call the parent’s constructor.

Parameters

$provider
Hustle_Provider_Abstract
An instance of your integration main class. Which is an instance of Hustle_Provider_Abstract.

Return

There’s nothing to return.

Example


form_settings_wizards()

Description

Optional.

With this method, you will be able to display a form with settings for users to configure your integration. On these settings is where you allow users to save their API key, email list name, webhook URL, or anything your integration requires to work properly. This method is used by Hustle to get the settings from your integration to be displayed on each step and to get the values to be stored after submission.

Usage

Used by Hustle when getting the settings to be displayed and saving their values.

Override this method to define the module’s settings wizard.

Parameters

It doesn’t have any parameters.

Return

It must return an array. This array must contain one array for each settings step.

  • Each step must contain two key => value pairs.
  • One key must be named “callback”. Its value should be an array to be used as the first argument for call_user_func() function.
  • The other key must be named “is_completed”. Its value should be an array to be used as the first argument for call_user_func() function.
  • The array might contain the number of steps your integration requires.

 

Below is explained how each of these two functions works.

Example


first_step_callback()

Description

You can name this method as you wish, as long as it’s properly defined at Hustle_Provider_Abstract::form_settings_wizards() method. This method handles the wizard steps by returning an array of key => value pairs.

Usage

Used by Hustle when retrieving the settings to be shown and the data to be saved.

Override it to set the wizard steps for your integrations.

Parameters

$submitted_data
Array
Array with the submitted data. Sanitized by Hustle_Api_Utils::validate_and_sanitize_fields().
$is_submit
Boolean
True when the call comes from a form submission. False otherwise. When true, it’s a good moment to validate the submitted data and return the values to be saved.
$module_id
Integer

Return

Associative array. It will handle the current step of settings. These are the expected keys and values:

  • ‘html’ => String. HTML markup of what’s inside the form for the current step.
  • ‘buttons’ => Array. It must contain an array for each “next” and “previous” button with its markup. If the helper functions are not used to get the markup, make sure your “Previous” button has the class “hustle-provider-prev”, and your “Next” button has the class. “hustle-provider-next” so the pagination works as expected.
  • ‘has_errors’ => Boolean. If true, the wizard will stay on the current step when the user clicks on the “next” button. Errors messages are shown.
  • ‘is_close’ => Boolean. If true, no settings will be shown and the modal will close. Useful when applying conditionals between steps. For example, when the setting required for the 4th step is optional and it’s not selected, simply set “is_close” as true in order to close the modal when arriving at this step under these conditions.

Example


is_first_step_completed()

Description

You can name this method as you wish, as long as it’s properly defined at form_settings_wizards() method.
This method is called when moving from one step to the following one. That is after the current step validation has been done and approved, and before the following step’s callback is called. This will check the previous steps have been completed before proceeding. If false, the previous step will be shown.

Usage

Used by Hustle when moving forward on the integration’s settings wizard.

Parameters

$submitted_data
Array
Array with the submitted data. Sanitized by Hustle_Api_Utils::validate_and_sanitize_fields().

Return

Boolean.
TRUE => If the step is completed.
FALSE => If the step is not completed.

Example

6.9 Methods to Use: Form Settings

Link to chapter 9
get_current_data()

Description

Helper. Get the current module settings for the integration. Receives an array with the name of the settings to retrieve and it’s a default value, and another array with the submitted data. If the setting is not in the submitted data, this function will retrieve it from the stored settings. The defaults will be used if the setting wasn’t found. Handles the stored settings for multi-instances if the property $is_multi_on_form is set to “true”.

Usage

Use it to retrieve a merge of your provider’s stored module settings, with the submitted values, and defaults as a fallback.

Parameters

$default_data
Array
Associative array. Use the name of the setting to retrieve as the key and the default value as its value.
$submitted_data
Array
Array with the submitted data.

Return

Associative array. The settings names will be the keys, and their stored value will be the value of the pair.

Example


get_form_settings_values()

Description

Retrieve the stored module settings of your provider.

Usage

Use it to retrieve the stored module settings of your provider.

Parameters

$get_cached
Boolean
Whether to retrieve the cached value of this.
Default: true.

Return

Array

Example


save_form_settings_values()

Description

Saves the given array as the provider’s module settings. If your provider allows multi-instances on modules, you can use the helper method “Hustle_Provider_Form_Settings_Abstract::save_form_multi_id_settings_values()”.

Usage

Use it to save the given array as your provider’s module settings.

Parameters

$values
Array
The associative array with the values to be stored.

Return

There’s nothing to return.

Example


save_form_multi_id_settings_values()

Description

Helper. Saves the given array as the provider’s settings for the given global multi-instance ID.

Uses “Hustle_Provider_Form_Settings_Abstract::save_form_settings_values()”.

Usage

Use it to save the given array as your provider’s settings for the given global multi-instance ID.

Parameters

$values
Array
Array with the values to be stored. If the key “multi_id” is not present in the array, a new ID will be created.

Return

There’s nothing to return.

Example

6.10 Class: Hustle_Provider_Form_Hooks_Abstract

Link to chapter 10

Description

Extend this class to perform actions on your provider’s side when certain actions happen in Hustle’s side. What this class does:

-Adds custom fields to the frontend form.

-Performs a validation to data submitted from the frontend, and makes the submission fail if needed.

-Sends the data submitted by frontend users to your provider’s API.

-Lets the admin know about the status of the subscription (or any action) done by the form submission in the Emails lists global page.

Example

6.11 Properties: Form Hooks

Link to chapter 11

Description

These are the useful properties for you within Hustle_Provider_Form_Hooks_Abstract class.

Properties to be defined

$_submit_form_error_message
String
The error message to be shown on frontend when there’s an error in Hustle_Provider_Form_Hooks_Abstract::on_form_submit().
Assign the class’ constant “ALREADY_SUBSCRIBED_ERROR” to use the shared error for when an email is already subscribed.
-Default: ‘’.
-protected

Properties to be used

$provider
Hustle_Provider_Abstract
Instance of the main class of your integration. protected
$form_settings_instance
Hustle_Provider_Form_Settings_Abstract
Instance of the form settings of your integration. protected
$module_id
Integer
ID of the current module that’s making use of this class. protected

6.12 Methods to Define: Form Hooks

Link to chapter 12
on_form_submit()

Description

Optional.

Define the validation your provider need. Make the whole form of submission fail if required. Set a string to the property Hustle_Provider_Form_Hooks_Abstract::_submit_form_error_message to display this message in frontend.

Usage

Called by Hustle on form submission to run a validation done by providers. For extending. Extend it to apply your own validation. Ignore if you don’t need to make the submission fail under any condition.

Parameters

$submitted_data
Array
An array containing the submitted data from the step.
$allow_subscribed
Boolean
Whether to make the submission fail if the user was already subscribed. Defined in the module’s Integrations tab settings.

Return

True on success. Anything else on failure.

Example


add_entry_fields()

Description

Required.

Extend this method to connect Hustle with your API. This method is called on form submission after the validation from all providers was done and there weren’t errors. Optionally, you can add data related to the request to the current entry (this is each submission you see on the Emails Lists page). See Hustle_Provider_Form_Hooks_Abstract::on_entry_render() on how to actually display it.

Usage

Called by Hustle after the form submission was done and all validations were successfully passed. Extend it to send your data to your API, and optionally store data in the current entry.

Parameters

$submitted_data
Array
An array containing the submitted data from the step.

Return

Array. It must be a multi-array with this format, or will be ignored otherwise:
array(
‘name’ => NAME,
‘value’ => VALUE’, => can be an array/object/scalar, it will be serialized on storage.
),
array(
‘name’ => NAME,
‘value’ => VALUE’
)

Example


on_render_entry()

Description

Optional.

Display the data from when your provider connected to its API on the Emails List page.

Usage

Called by Hustle when rendering the module’s submissions on the Emails List page. Extend this method to display the data you stored on Hustle_Provider_Form_Hooks_Abstract::add_entry_fields() on the entries’ details from the Emails List page. You might not need to extend the base method if your provider already stores what’s used in there.

Parameters

$entry_model
Hustle_Entry_Model
Instance of Hustle_Entry_Model
$addon_meta_data
Array
Specific meta_data added by your provider at Hustle_Provider_Form_Hooks_Abstract::add_entry_fields()

Return

Array. It must be a multi-array with this format, or will be ignored otherwise:
array(
‘name’ => NAME,
‘value’ => VALUE’, => its output is on html mode, so you can do styling. Don’t forget to escape!
),
array(
‘name’ => NAME,
‘value’ => VALUE’
)

Example


add_front_form_fields()

Description

Optional.

Display custom fields in the frontend form.

Usage

Called by Hustle after the core form’s fields are retrieved. Extend this method to add form fields to the frontend form.

Parameters

$module
Hustle_Module_Model
Instance of Hustle_Module_Model

Return

String. The HTML code to be added after the core form’s fields.

Example

6.13 Helper Functions

Link to chapter 13
hustle_get_html_for_options()

Description

Use Hustle’s options template to get the HTML for the given array of options.

Usage

hustle_get_html_for_options( $options );

Parameters

$options
Array
Array with the options to be rendered as HTML.

Return

String with the markup.

Example


hustle_get_integration_modal_title_markup()

Description

Retrieve the markup for the title of the provider’s modal.

Usage

hustle_get_integration_modal_title_markup( $options );

Parameters

$title
String
Title to be displayed.
Default: ‘’.
$subtitle
String
Subtitle to be displayed.
Default: ‘’.
$class
String
Class to be added to the outer wrapper of the title group.
Default: ‘’.

Return

String with the markup.

Example


hustle_get_provider_button_markup()

Description

Retrieve the markup for the buttons of the provider’s modal.

Usage

hustle_get_provider_button_markup( $options );

Parameters

$value
String
Text to be shown within the button.
Default: ‘’.
$class
String
Extra class for the button.
Default: ‘’.
$action
String
Action that this button should perform, if any
Possible values: next|prev|close|connect|disconnect|disconnect_form.
Default: ‘’.
$loading
Boolean
Whether the buttons need the “loading” attributes.
Default: ‘’.
$disabled
Boolean
Whether the button should be disabled on load.
Default: ‘’.

Return

String with the markup.

Example


hustle_provider_maybe_log()

Description

Add an entry to the debug.log file. For that to happen the constants “WP_DEBUG”, “HUSTLE_DEBUG”, and “HUSTLE_PROVIDER_DEBUG”  must be defined and set to true.

Usage

hustle_provider_maybe_log( $error_data );

Parameters

This function grabs all the function’s arguments so the number of parameters is only limited by the “func_get_args()” function. Also, the resulting array is JSON encoded to be printed as a string.

$error_data
Mixed
The data to be printed in debug.log. It will be JSON encoded.

Return

There’s nothing to return.

Example

Hi, I’m available right now to answer any of your questions :)

Email Us Chat Now Find out more