Before we dive into developing a custom integration for Automator, let's explain some of the…
Adding a Settings Page for an App Integration
5.
Adding a Settings Page for an App Integration
Let’s add a Settings page to our integration. This settings page will allow users to enter some value and store it, for example, an API key:
The settings file and class
You can view the complete code of this file here, or you can download the whole sample plugin from our GitHub repository.
Let’s be organized and create the settings folder inside our integration. Then create the settings-sample.php file in it.
In that file, define the new Sample_Integration_Settings class that extends the \Uncanny_Automator\Settings\Premium_Integration_Settings class:
<?php
class Sample_Integration_Settings extends \Uncanny_Automator\Settings\Premium_Integration_Settings {
public function set_properties() {
// The unique page ID that will be added to the URL
$this->set_id( 'sample-integration' );
// The integration icon will be used for the settings page, so set this option to the integration ID
$this->set_icon( 'SAMPLE_INTEGRATION' );
// The name of the settings tab
$this->set_name( 'Sample integration' );
// Use this method to register an option for each field your settings page will have
$this->register_option( 'sample_api_key' );
}
}
In the set_properties method, define the page’s unique ID using the set_id method. This ID will be used to create the unique settings page URL.
For now, premium integration settings pages have to be assigned to some integration. The icon of the settings page will be taken from the integration, so you will need to pass the integration ID to the set_icon method.
Pass the settings page title to the set_name method.
Use the register_option method for each field that you plan to have on the settings page. In this case, we will only have one field for the API key, so we pass ‘sample_api_key’ to it.
Instantiating the Settings class
Now let’s get back to uncanny-automator-sample.php file, and add the following line at the end of the sample_integration_load_files function:
require_once 'settings/settings-sample.php';
new Sample_Integration_Settings();
Note the we can pass any number of dependencies to the class and they will be available in $this->dependencies array.
Integration status
The next method we need to define is the get_status:
public function get_status() {
// Not connected by default
$this->is_connected = false;
// Get the API key
$this->api_key = get_option( 'sample_api_key', false );
// If there is an API key, we are connected
if ( false !== $this->api_key ) {
// Store the connected status for later use
$this->is_connected = true;
// Return this string to show the green checkmark
return 'success';
}
// Return an empty string if not connected
return '';
}
This method will be used by the sidebar to add a checkmark icon next to the integrations that are connected:
The get_status has to return the ‘success’ string if your integration is connected/active and an empty string otherwise.
In our code example, we only check if there is an API key stored to determine if our integration is connected.
We will also save the connected status in the $this->is_connected variable for later use.
Now let’s output the settings tab content.
public function output_panel_content() {
// If the integration is not connected, output the field
if ( ! $this->is_connected ) {
$args = array(
'id' => 'sample_api_key',
'value' => $this->api_key,
'label' => 'API key',
'required' => true,
);
$this->text_input( $args );
} else { // If the integration is connected, output the success message
?>
<p> <?php echo __( 'You have successfully connected!', 'automator-sample' ); ?> </p>
<?php
}
}
Overwrite the output_panel_content content method. This method can output plain HTML or you can use the class methods to output some elements. In this case we use $this->text_input( $args ); method to show the field when not connected and a paragraph with the success message as well.
Next, let’s output the buttons in the bottom right corner:
public function output_panel_bottom_right() {
// If we are connected, output the Save button
if ( ! $this->is_connected ) {
$button_label = __( 'Save settings', 'automator-sample' );
$this->submit_button( $button_label );
} else {
// Otherwise, show a button that will redirect with the disconnect flag in the URL
$button_label = __( 'Disconnect', 'automator-sample' );
$link = $this->get_settings_page_url() . '&disconnect=1';
$this->redirect_button( $button_label, $link );
}
}
We need to override the output_panel_bottom_right method and check if we are not connected, use the submit_button method to output the save button. Otherwise, output a button that will simply redirect to the same page with the &disconnect=1 flag in the URL.
Let’s go back to the set_properties method and add a line that will attach the disconnect handler to the init WP hook:
public function set_properties() {
// The unique page ID that will be added to the URL
$this->set_id( 'sample-integration' );
// The integration icon will be used for the settings page, so set this option to the integration ID
$this->set_icon( 'SAMPLE_INTEGRATION' );
// The name of the settings tab
$this->set_name( 'Sample integration' );
// Use this method to register an option for each field your settings page will have
$this->register_option( 'sample_api_key' );
// Handle the disconnect button action
add_action( 'init', array( $this, 'disconnect' ) ); //<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< Add this
}
And create a method that will delete the settings if there is the disconnect=1 flag in the URL found:
public function disconnect() {
// Make sure this settings page is the one that is active
if ( ! $this->is_current_page_settings() ) {
return;
}
// Check that the URL has our custom disconnect flag
if ( '1' !== automator_filter_input( 'disconnect' ) ) {
return;
}
// Delete the API key
delete_option( 'sample_api_key' );
// Redirect back to the settings page
wp_safe_redirect( $this->get_settings_page_url() );
exit;
}
The last method we probably should override is the settings_updated:
public function settings_updated() {
// Get the setting
$this->api_key = get_option( 'sample_api_key', false );
// Run any validation and add alerts
if ( is_numeric( $this->api_key ) ) {
// Display a success message
$this->add_alert(
array(
'type' => 'success',
'heading' => __( 'Your API key is a number!', 'automator-sample' ),
'content' => 'Additional content'
)
);
} else {
// Delete the invalid APi key
delete_option( 'sample_api_key' );
// Display an error
$this->add_alert(
array(
'type' => 'error',
'heading' => __( 'Your API key is not a number!', 'automator-sample' ),
'content' => __( 'The API key failed the numeric check', 'automator-sample' ),
)
);
}
}
This method will run whenever someone clicks the Save button. In this case, we check that the API key is a numeric value and add a green or red alert depending on the result. The alerts will be added under the settings page title:
Now your plugin can use the sample_api_key option anywhere to connect to your services and you can use that option to check if your integration is connected or not.
Checkout other articles from this series: