How to create a simple trigger with Automator

4. How to create a simple trigger with Automator

5. How to create a simple Automator action

Difficulty: Easy

Creating a trigger with Automator 3.0 is a lot easier than you might think. To get started, you can download this working sample from our Github repository.

A step by step guide to create a simple user visits a page trigger with Automator 3.0+:

Start by creating a new plugin in your dev environment and define your plugin file:

<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName

/**
 * @wordpress-plugin
 * Plugin Name:       Your plugin name
 * Plugin URI:        Your plugin URI
 * Description:       Your plugin description
 * Version:           1.0.0
 * Author:            Author
 * Author URI:        Author URI
 * License:           GPL-3.0+
 * License URI:       http://www.gnu.org/licenses/gpl-3.0.txt
 */

After defining your plugin, use automator_add_trigger() to add your trigger in Automator’s active triggers as:

function load_my_custom_triggers() {
	// Let's find integration by name so that trigger can be added to it's list.
	$add_to_integration = automator_get_integration_by_name( 'Uncanny Automator' );
	if ( empty( $add_to_integration ) ) {
		return null;
	}
    // Add a php trigger file in the same folder and name it uoa-uservisitspage.php
	$trigger = __DIR__ . '/uoa-uservisitspage.php';
	automator_add_trigger( $trigger, $add_to_integration );
}

add_action( 'automator_configuration_complete', 'load_my_custom_triggers' );

Once the trigger is defined, you will now create a file in plugin folder (if not created yet) and name it uoa-uservisitspage.php.

Automator usually uses integration’s shortcode as the prefix of the file and class name, i.e., uoa is the shortcode of Uncanny Automator integration and uservisitspage is somewhat meaningful name of the trigger’s functionality. The classname from filename uoa-uservisitspage will become UOA_USERVISITSPAGE.

Now in trigger file, start by adding use Uncanny_Automator\Recipe namespace. Declare your class.

<?php

use Uncanny_Automator\Recipe;

class UOA_USERVISITSPAGE {
}

Automator 3.0 uses PHP’s Traits to implement consistent code across all integration files. Add use Recipe\Triggers inside your class as:

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_USERVISITSPAGE
 */
class UOA_USERVISITSPAGE {
	use Recipe\Triggers;

}

As soon as use Recipe\Triggers is added, your IDE should throw a notice that there are few abstract functions that are required to be added in to the file. These function are mandatory to run a trigger and has to be added in the trigger file. Your site will also throw a Fatal error if not added. These functions are:

protected function setup_trigger(){}    // Is used to declare trigger
protected function validate_trigger(){} // Is used to validate trigger once it's triggered
protected function prepare_to_run(){}   // Is used to set some values to help the trigger process

You will now add placeholder functions like:

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_USERVISITSPAGE
 */
class UOA_USERVISITSPAGE {
	use Recipe\Triggers;

	protected function setup_trigger() {
	}

	protected function validate_trigger( $args ) {
	}

    protected function prepare_to_run( $args ) {
    }
}

Once you are done adding placeholder functions, next step is to actually setup_trigger() so that it’s added in Automator’s Recipe UI. To do that, add __construct() and call setup_trigger().

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_USERVISITSPAGE
 */
class UOA_USERVISITSPAGE {
	use Recipe\Triggers;

    public function __construct() {
		$this->setup_trigger();
	}

	protected function setup_trigger() {
	}

	protected function validate_trigger( $args ) {
	}

    protected function prepare_to_run( $args ) {
    }

}

You will use following functions in order to define a trigger:

$this->set_integration(); // Display this trigger under specific integration 

$this->set_trigger_code(); // Unique Trigger code

$this->set_trigger_meta(); // Re-useable meta, selectable value in blue boxes

$this->set_sentence(); // Sentence to appear when trigger is added.

$this->set_readable_sentence(); // Non-active state sentence to show

$this->add_action(); // which do_action() triggers this trigger 

$this->set_options(); // Adding options so that Automator could display it in Recipe UI 

$this->register_trigger(); // Registering this trigger

To get the list of all available functions for setup_trigger(), please refer to Trigger_Setup developer’s guide here.

Now let’s start to fill values in this trigger by adding above functions in setup_trigger():

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_USERVISITSPAGE
 */
class UOA_USERVISITSPAGE {
	use Recipe\Triggers;

    public function __construct() {
		$this->setup_trigger();
	}

	protected function setup_trigger() {

		$this->set_integration( 'UOA' ); // Display this trigger under UOA integration 

		$this->set_trigger_code( 'USERVISITSPAGE' ); // Unique Trigger code

		$this->set_trigger_meta( 'WPPAGE' ); // Re-useable meta, selectable value in blue boxes

		/* Translators: Some information for translators */
		$this->set_sentence( sprintf( 'My site user views {{a page:%1$s}}', $this->get_trigger_meta() ) ); // Sentence to appear when trigger is added. {{a page:%1$s}} will be presented in blue box as selectable value

		/* Translators: Some information for translators */
		$this->set_readable_sentence( 'My site user views {{a page}}' ); // Non-active state sentence to show

		$this->add_action( 'template_redirect', 20, 1 ); // which do_action() fires this trigger 

		$options = array(
			Automator()->helpers->recipe->wp->options->all_pages(), // Add your options for this trigger
		);

		$this->set_options( $options ); // Adding options so that {{a page:%1$s}} could display it in Recipe UI 

		$this->register_trigger(); // Registering this trigger
	}

	protected function validate_trigger( $args ) {
	}

    protected function prepare_to_run( $args ) {
    }

}

At this point, if all goes well, the trigger should start to show up in Recipe UI as:

Trigger in the Recipe UI

Trigger displaying option

Trigger once option is selected

The trigger is technically ready for use on your Automator installation site.

But wait, what happens when the trigger fires?

This is handled in the following functions that you added before as placeholders:

protected function validate_trigger( $args ) {}

protected function prepare_to_run( $args ) {}

By default, all triggers are going to call Triggers::validate() function. This function accepts any number of arguments by using Splat Operator ... in the form of an array.

For this trigger, template_redirect does not pass any argument.

Next step, as the name suggests, validate_trigger(), you are going to do some basic validation before its passed back to Automator for further processing.

protected function validate_trigger( $args ) {
    // check if current displayed page is of type page
    // and not an archive page, you can use is_post() to check if it's a post
	if ( ! is_page() && ! is_archive() ) {
		return false;
	}

	return true;
}

This trigger is only going to run if user visited a page and is not an archive page. validate_trigger must return true or false back to Automator. The trigger file now will be:

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_RECIPENOTCOMPLETED
 */
class UOA_RECIPENOTCOMPLETED {
	use Recipe\Triggers;

    public function __construct() {
		$this->setup_trigger();
	}

	protected function setup_trigger() {

		$this->set_integration( 'UOA' ); // Display this trigger under UOA integration 

		$this->set_trigger_code( 'USERVISITSPAGE' ); // Unique Trigger code

		$this->set_trigger_meta( 'WPPAGE' ); // Re-useable meta, selectable value in blue boxes

		/* Translators: Some information for translators */
		$this->set_sentence( sprintf( 'My site user views {{a page:%1$s}}', $this->get_trigger_meta() ) ); // Sentence to appear when trigger is added. {{a page:%1$s}} will be presented in blue box as selectable value

		/* Translators: Some information for translators */
		$this->set_readable_sentence( 'My site user views {{a page}}' ); // Non-active state sentence to show

		$this->add_action( 'template_redirect', 20, 1 ); // which do_action() fires this trigger 

		$options = array(
			Automator()->helpers->recipe->wp->options->all_pages(), // Add your options for this trigger
		);

		$this->set_options( $options ); // Adding options so that {{a page:%1$s}} could display it in Recipe UI 

		$this->register_trigger(); // Registering this trigger
	}

	public function validate_trigger(): bool {

		if ( ! is_page() && ! is_archive() ) {
			return false;
		}

		return true;
	}

	protected function prepare_to_run( $args ) {
	}
}

The last step is to provide Automator with post_id to process the trigger further and call other triggers/actions of the recipe. To set post_id, add the following code:

protected function prepare_to_run( $args ) {
	// Set Post ID here.
	global $post;  // Get the post ID of the current page
	$this->set_post_id( $post->ID );
}

Your trigger file is now complete and will look like this:

<?php

use Uncanny_Automator\Recipe;

/**
 * Class UOA_RECIPENOTCOMPLETED
 */
class UOA_RECIPENOTCOMPLETED {
	use Recipe\Triggers;

    public function __construct() {
		$this->setup_trigger();
	}

	protected function setup_trigger() {

		$this->set_integration( 'UOA' ); // Display this trigger under UOA integration 

		$this->set_trigger_code( 'USERVISITSPAGE' ); // Unique Trigger code

		$this->set_trigger_meta( 'WPPAGE' ); // Re-useable meta, selectable value in blue boxes

		/* Translators: Some information for translators */
		$this->set_sentence( sprintf( 'My site user views {{a page:%1$s}}', $this->get_trigger_meta() ) ); // Sentence to appear when trigger is added. {{a page:%1$s}} will be presented in blue box as selectable value

		/* Translators: Some information for translators */
		$this->set_readable_sentence( 'My site user views {{a page}}' ); // Non-active state sentence to show

		$this->add_action( 'template_redirect', 20, 1 ); // which do_action() fires this trigger 

		$options = array(
			Automator()->helpers->recipe->wp->options->all_pages(), // Add your options for this trigger
		);

		$this->set_options( $options ); // Adding options so that {{a page:%1$s}} could display it in Recipe UI 

		$this->register_trigger(); // Registering this trigger
	}

	public function validate_trigger(): bool {

		if ( ! is_page() && ! is_archive() ) {
			return false;
		}

		return true;
	}

	protected function prepare_to_run() {
		// Set Post ID here.
		global $post;
		$this->set_post_id( $post->ID );

	}
}

The trigger is now ready to be used in a recipe.

Difficulty: Easy

A step by step guide to create a simple user visits a page trigger with Automator 3.0+:

But wait, what happens when the trigger fires?

Share This

Related Posts