Hey, WordPress web developer :)

Check out WPMU DEV

Skip to Main Content
Docs / / Hustle Providers API Doc

6. Hustle Providers API Doc

Written by Danae | Last updated: September 13, 2018
General
To register your integration into Hustle’s framework
/inc/hustle-providers.php
Class to extend and create your main integration’s class
/inc/provider/hustle-provider-abstract.php
Properties for your main integration class
/inc/provider/hustle-provider-abstract.php
To prevent your integration from being instantiated
/inc/provider/hustle-provider-abstract.php
To prevent your integration from being included in Hustle’s lists
/inc/provider/hustle-provider-abstract.php
To retrieve your integration’s data saved in a module
/inc/provider/hustle-provider-abstract.php
To submit the opt-in form data to your integration
/inc/provider/hustle-provider-abstract.php
To pass arguments to your frontend template
/inc/provider/hustle-provider-abstract.php
To make sure your settings are valid
/inc/provider/hustle-provider-abstract.php
Class to extend and create your integration’s settings class
/inc/provider/hustle-provider-form-settings-abstract.php
Properties for your integration’s settings class
/inc/provider/hustle-provider-form-settings-abstract.php
To handle the actions on your settings instantiation
/inc/provider/hustle-provider-form-settings-abstract.php
To define your settings steps
/inc/provider/hustle-provider-form-settings-abstract.php
To handle the first step from your settings
/inc/provider/hustle-provider-form-settings-abstract.php
To verify the previous step was completed
/inc/provider/hustle-provider-form-settings-abstract.php
To get the default ‘cancel’ button markup
/inc/provider/hustle-provider-form-settings-abstract.php
To get the default ‘previous’ button markup
/inc/provider/hustle-provider-form-settings-abstract.php
To get the default ‘next’ button markup
/inc/provider/hustle-provider-form-settings-abstract.php
To get a markup providing an array with options
/inc/provider/hustle-provider-form-settings-abstract.php
To modify the data to be saved
/inc/provider/hustle-provider-form-settings-abstract.php
Class with helper methods
/inc/hustle-api-utils.php
To make sure an AJAX call is legit
/inc/hustle-api-utils.php
To check if required fields are set
/inc/hustle-api-utils.php
To render or get the contents of a template file
/inc/hustle-api-utils.php
To add an entry to the error log
/inc/hustle-api-utils.php
Shortcut to register AJAX endpoints
/inc/hustle-api-utils.php
To sanitize and validate submitted data
/inc/hustle-api-utils.php
To display saved values
/inc/provider/hustle-provider-form-settings-abstract.php
To do AJAX requests
/inc/provider/hustle-provider-form-settings-abstract.php

6.1 Method: register_provider()

Link to chapter 1

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 into Hustle if the requirements are not met.

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

Usage

Hustle_Providers::register_provider( $class_name );

Parameters

$class_name
String | Object
If it’s an object, it must be an instance of Hustle_Provider_Abstract. The class name of the integration. Or an instance of the main integration class.

Example

Hustle_Providers::register_provider( ‘My_Integration_Class’ );

Return

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

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

6.2 Class: Hustle_Provider_Abstract

Link to chapter 2

Description

Extend this class to create integrations.

Example

6.3 Properties: Hustle_Provider_Abstract

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

$_slug
String
-Required. Protected. 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.
$_version
String
-Required. Protected. The version number of the integration.
$_class
String
-Required. Protected. The class name of the integration.
$_title
String
-Required. Protected. Title of the integration that will be shown to users.
$_min_hustle_version
String
-Required. Public. Static. The 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. If not defined by your integration, the minimum Hustle version is set to 3.0.5.
$_min_php_version
String
-Required. Public. Static. The minimum version of PHP so the provider works properly. The provider won’t be loaded if the current PHP version is lower than this one. If not defined by your integration, the minimum PHP version is set to the constant PHP_VERSION, meaning that your integration will load for all PHP versions.
$_supports_fields
Boolean
-Required. Protected. Whether the integration supports custom fields. Setting it as false will disable adding fields to opt-in forms. If not overridden, it’s set as False by default.
$_front_args
String
-Optional. Protected. The path to the template that will be included in the frontend, if the integration has any. Passed to the “include” statement. This template will be inserted within <script> tags, so javascript can be included in that file.
$_icon
String
-Optional. Protected. Icon URL that will be displayed when the provider is selected. It should be either the full URL of the image to be used for the “src” attribute of “img” tags, or a PHP file to be included, currently used for SVG icons.
$_icon_x2
String
-Optional. Protected. Required if your $_icon property is an image. Retina icon URL that will be displayed when the provider is selected. Used for the “src” attribute of “img” tags. If your $_icon is an image (JPG or PNG), this property is required for your icon to show up.
$_form_settings
String | Null
-Optional. Protected. The class name of integration’s settings in string or empty if form setting is not needed. Must exist at runtime.
$_provider_form_settings_instances
Object | Null
-Must not be overridden. Protected. An instance of Hustle_Provider_Form_Settings_Abstract, null if not needed. Hustle will assign the value to this property.

Example

6.4 Method: get_instance()

Link to chapter 4

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.

Example

Return

Object. Instance of your provider class.

6.5 Method: check_is_compatible()

Link to chapter 5

Description

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.

Override this method if you have another logic for checking if your integration is compatible.

Usage

Used by Hustle when filtering out the providers that should not be loaded.

Parameters

$class_name
String
The class name of the integration.

Example

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.

6.6 Method: check_is_activable()

Link to chapter 6

Description

This method is called by is_activable() to verify if the integration can be activated. The final validation of the integration is done in 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.
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.

Usage

Used by Hustle when filtering out the providers that should not be loaded.
$my_integration_instance->check_is_activable();

Parameters

It doesn’t have any parameters.

Example

Return

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

6.7 Method: get_provider_details()

Link to chapter 7

Description

Public static method. This method is used to retrieve the integration’s data stored in a module.

Usage

My_Integration_Class::get_provider_details( $module_id, $field, $slug );

Parameters

$module_id
Integer | Object
Instance of Hustle_Module_Model or ID of the module from where the data will be retrieved.
$field
String
The name of the setting to be retrieved.
$slug
String
Slug of the provider to whom the data belongs.

Example

Return

Mixed => The saved data.
Empty string => If the module doesn’t exist or it doesn’t contain the requested data.

6.8 Method: subscribe()

Link to chapter 8

Description

This method is called when an opt-in form is submitted on the frontend. You must override this method in order to connect Hustle’s forms with your integration’s application. Here’s where the data submitted by the users is sent to the external application you wish.

The default fields from Hustle’s opt-in form are named:

  • ’email’: e-mail address field.
  • ‘first_name’ (‘f_name’ on previous versions): first name field.
  • ‘last_name’ (‘l_name’ on previous versions): last name field.

Other data included on form submission by default is:

  • ‘module_id’: id of the module from which the data is submitted.
  • ‘page_type’: post type from where the submission was done.
  • ‘page_id’: id of the post from where the submission was done.
  • ‘uri’: URL from where the data is submitted.
  • ‘type’: type of the module doing the submission. If it’s a Pop-Up, a Slide-in, or an Embed.

Any other field is considered a custom field. If your integration doesn’t support custom fields, these are the only fields you’ll need to handle.

Usage

Called by Hustle when the opt-in form is submitted and your integration is active.
$my_integration_instance->subscribe( $module, $data );

Parameters

$module
Object
An instance of Hustle_Module_Model of the module from where the form is submitted.
$data
Array
Contains all the fields submitted by the user using the opt-in form.

Example

Return

TRUE => If the data was submitted and handled successfully.
WP_Error => If something went wrong. The message within the WP_Error will be shown on the frontend to the user submitting the form.

6.9 Method: get_args()

Link to chapter 9

Description

Override this method to set an array of arguments that will be available for you to handle them within the template defined in the $_front_args property of your integration. Include any variables your integration may require when displaying the template on frontend by returning them on this method as an array.

This method is optional but must return a filled array if your integration is using a template in the frontend.

The values returned by this method will be available on your template within the $args array, and also as javascript variables.

The parameter $data contains the settings of the module that’s being displayed. This way you can get the values that are stored within the module in order to handle what your frontend template will display.

Usage

Used by Hustle to pass your arguments to your template defined in the $_front_args property.

Parameters

$data
Array
Contains the content settings of the module displaying the template.

Example

Return

Array.

6.10 Method: is_form_settings_available()

Link to chapter 10

Description

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.

Parameters

It doesn’t have any parameters.

Example

Return

Boolean.
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 on the integration’s settings is not a valid array.
  • The number of steps defined on 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.

6.11 Class: Hustle_Provider_Form_Settings_Abstract

Link to chapter 11

Description

Extend this class to create the settings for your integration.

Example

6.12 Properties: Hustle_Provider_Form_Settings_Abstract

Link to chapter 12

Description

Useful properties for your integration within Hustle_Provider_Form_Settings_Abstract class.

Properties

$provider
Object
Protected. Instance of Hustle_Provider_Abstract. Main instance of your integration.

6.13 Method: __construct()

Link to chapter 13

Description

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.

Parameters

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

Example

Return

There’s nothing to return.

6.14 Method: form_settings_wizards()

Link to chapter 14

Description

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.

Parameters

It doesn’t have any parameters.

Example

Return

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.

6.15 Method: first_step_callback()

Link to chapter 15

Description

You can name this method as you wish, as long as it’s properly defined at form_settings_wizards() method. This method handles the settings of the step it belongs to 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.

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.

Example

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.
  • ‘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.
  • ‘data_to_save’ => Array. The data that will be stored in the current module. It might be the same $submitted_data. You might also make some adjustments or add extra information to the data that’s stored according to the selected settings. It’s convenient to save this data when it’s a submission and there are no errors.

The keys has_errors, is_close, and submitted_data are optional.

The values saved on one step will be available on the next step.

6.16 Method: is_first_step_completed()

Link to chapter 16

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().

Example

Return

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

6.17 Method: get_cancel_button_markup()

Link to chapter 17

Description

This is a helper method to get the default Hustle’s markup for the “Cancel” button of the integration settings wizard.

Usage

$this->get_cancel_button_markup();

Parameters

$value
String
Optional. The text that will be shown in the button.
$class
String
Optional. Custom class to add to the button.

Example

Return

String with the button’s markup.

6.18 Method: get_previous_button_markup()

Link to chapter 18

Description

This is a helper method to get the default Hustle’s markup for the “Previous” button of the integration settings wizard.

Usage

$this->get_previous_button_markup( $value, $class );

Parameters

$value
String
Optional. The text that will be shown in the button.
$class
String
Optional. Custom class to add to the button.

Example

Return

String with the button’s markup.

6.19 Method: get_next_button_markup()

Link to chapter 19

Description

This is a helper method to get the default Hustle’s markup for the “Next” button of the integration settings wizard.

Usage

$this->get_next_button_markup();

Parameters

$value
String
Optional. The text that will be shown in the button.
$class
String
Optional. Custom class to add to the button.

Example

Return

String with the markup.

6.20 Method: get_html_for_options()

Link to chapter 20

Description

This is a helper method that uses Hustle’s template files for options to render the HTML given an array of options.

Usage

$this->get_html_for_options( $options );

Parameters

$data
Array
Contains all the fields submitted by the user using the opt-in form.

Example

Return

String with the markup.

6.21 Method: before_save_first_step()

Link to chapter 21

Description

Helper method. This method modifies the data of the integration to be saved into the module. If $submitted_value[‘api_key’] is set, this method will add the key ‘desc’ to $submitted data, with the value of $submitted_value[‘api_key’].
The value of $submitted_data[‘desc’] is what will be shown below the Provider’s title and above the text saying “Click here to edit or change your email provider”, under “Email collection module” section on “Content” tab.

Usage

$data_to_be_saved = $this->before_save_first_step( $submitted_data );

Parameters

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

Example

Return

Array.

6.22 Class: Hustle_Api_Utils

Link to chapter 22

Description

This class contains public static methods expected to be helpers when building your integration.

Example

Hustle_Api_Utils::register_ajax_endpoints( ‘My_Integration_Class_Name’ );

6.23 Method: validate_ajax_call()

Link to chapter 23

Description

This method will verify if the user making the request is allowed to make changes, and if the nonces are correct by checking current_user_can( ‘manage_options’ ), and check_ajax_referer( $action, false, false ). If validation fails, a JSON error is sent back.

Usage

Hustle_Api_Utils::validate_ajax_call( $action );

Parameters

$action
String
Name of the action triggering the AJAX call.

Example

Return

Triggers a failure JSON response => If the request didn’t pass validation.

6.24 Method: check_for_required_fields()

Link to chapter 24

Description

Used for checking required fields on form submissions. The names passed on $required_fields are searched into $post_data array keys. If the key is not set, an array with the key “errors” is returned. The error message by default is ‘%s is required.’, which is used in ‘sprintf’ to include the name of the field that’s missing. It checks if the field is set and if it’s not empty.

$required_fields should be an associative array and have the name of the required field as it is on $submitted_data as the keys and the name to be shown to the user as the value.

Usage

Hustle_Api_Utils::check_for_required_fields( $submitted_data, $required_fields, $error_message );

Parameters

$submitted_data
Array
Array with the data to be checked.
$required_fields
Array
Associative array with the field names to be searched in $submitted_data.
$error_message
String
Optional. Error message to be used within sprintf function to add the name of the missing field. For example ‘%s is required.’.

Example

Return

Array.
Empty array => If all required fields are set and not empty.
Filled array => If there are required fields missing.

If a required field is missing, the returned array will look like this:
$errors = array(
‘api_key’ => ‘Your API key is required’,
‘list_id’ => ‘The list is required’,
);

6.25 Method: static_render()

Link to chapter 25

Description

Helper method. It will either include or return the defined template file, according to the $return parameter.

Usage

Hustle_Api_Utils::static_render( $file, $params, $return );

Parameters

$file
String
Full path of the file to be processed.
$params
Array
Associative array. Its keys will be available as variables within the included file.
$return
Boolean
Whether the file should be returned as a string or included.

Example

Return

String => If the file exists and $return is true.

6.26 Method: maybe_log()

Link to chapter 26

Description

This method will use error_log to add entries to the log file if WP_DEBUG is enabled, or if the filter ‘hustle_enable_log’ returns True.

Usage

Hustle_Api_Utils::maybe_log( $message );

Parameters

All the parameters passed to this method will be concatenated to form a string for the log file.

Example

Hustle_Api_Utils::maybe_log( __METHOD__, ‘Server failed’, $this->get_error_message() );

Return

There’s nothing to return.

6.27 Method: register_ajax_endpoints()

Link to chapter 27

Description

This method will get an instance of $class_name and make a call to its method named “register_ajax_endpoints”. It’s a shortcut for registering non-static AJAX endpoints.

Usage

Hustle_Api_Utils::register_ajax_endpoints( ‘My_Provider_Class_Name’ );

Parameters

$class_name
String
Class name of the main integration class.

Example

Return

There’s nothing to return.

6.28 Method: validate_and_sanitize_fields()

Link to chapter 28

Description

This method will do a simple sanitation of $post_data. It’s intended to be used to sanitize form submissions. It applies sanitize_text_field() to the keys and values of the first level array. The keys from second level arrays are converted to numbers, and their values are sanitized with sanitize_text_field() as well.

This method doesn’t do an exhaustive sanitation, so you should handle special cases if your integration requires something different.

The names passed on $required_fields are searched into $post_data array keys. If the key is not set, an array with the key “errors” is returned.

Usage

Hustle_Api_Utils::validate_and_sanitize_fields( $post_data, $required_fields );

Parameters

$post_data
Array
Associative array with the data submitted.
$required_fields
Array
Array with the required field names.

Example

Return

Array.

If the required fields are missing, this array will contain a key named “errors”, which is an array with an error message for each field.

6.29 Process: Hustle_Provider_Form_Settings_Abstract. Displaying saved values.

Link to chapter 29

Description

Hustle doesn’t save the provider’s settings to the database until the user saves the module. This means that, even though the user went through all your settings steps and updated its values, these values won’t be shown when retrieving them from the database. These values are stored when the module is saved, not when the provider’s settings are saved.

Let’s say you’re retrieving the selected list name from the database in order to show it to the users, so they know which list is active. If the user changes the list, goes through the provider’s steps, and then open the provider modal again, the old value will show up, and not the one that was just selected.

To get the values that were selected but haven’t been saved into the database, you could look into the array $submitted_data passed to each step of the wizard. Another option to show the saved values as strings is by including in your markup an element with the class “current_{field-name}”. For example, <span class=”current_api_key”></span>. Hustle will fill these tags with the saved values.

Usage

$html = ‘<span class=”current_api_key”></span>’;

Example

6.30 Process: Hustle_Provider_Form_Settings_Abstract. Doing AJAX requests.

Link to chapter 30

Description

-Registering the endpoints:
The AJAX endpoints should be registered outside your provider’s settings class. The one extending Hustle_Provider_Form_Settings_Abstract. Registering them on the constructor won’t work. You could use the Hustle_Api_Utils::register_ajax_endpoints() helper method for this if you want your AJAX methods not to be static. If you’re using this helper method, make sure your settings class has a callable method called “register_ajax_endpoints”.

-Triggering the request:
There are two custom AJAX triggers available for your to use by default. These are identified by adding the following classes to each one of them:
On change, by adding the class “hustle_provider_on_change_ajax” to the element that should trigger the AJAX request when changed.
On click, by adding the class “hustle_provider_on_click_ajax” to the element that should trigger the AJAX request when clicked.

All the “data” attributes of the target will be passed to the backend, so you can include here any meaningful information. The “data” attributes handled by Hustle are:

  • “action”. Required. This is the AJAX request action.
  • “nonce”. Required. The nonce related to the AJAX action.
  • “dom_wrapper”. Optional. Example: “#options-wrapper”. When the request is triggered, the HTML of the DOM element with the identifier defined here will be replaced by a loading icon. Expecting to add some HTML in here retrieved from the AJAX response.

-Request response:
There are 3 possible actions to be triggered by the AJAX response, depending on what’s returned in the response array:

  • “html” and “wrapper”. Returning both of them will make Hustle replace the HTML of the DOM element defined in “wrapper” with the HTML defined in “html”.
  • “redirect_url”. Returning this in the response will redirect the user to the URL defined in here.
  • “is_close”. Returning this as ‘true’ will close the provider’s settings modal. Note that closing the modal will not save the settings of the current step.

Example

Live Chat

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

Chat Now
Email Us Find out more