Registering custom triggers

New, custom triggers can be easily registered in your plugin or theme. All you need is a simple class declaration and a function call.

Let’s pretend we have the following scenario: we are checking if any page with ?myparam is visited and if yes, we are triggering our notification. But if ?myparam=not-important we don’t want to do anything.

On the other hand, in the notification, we want to get a homepage URL with ?source parameter, which basically will have the value of ?myparam.

 

Let’s go to implementation. First, our action:

add_action( 'wp', function() {
	
	if ( isset( $_GET['myparam'] ) ) {

		if ( 'not-important' == $_GET['myparam'] ) {
			$process = false;
		} else {
			$process = true;
		}

		do_action( 'my_action_hook', $_GET['myparam'], $process );

	}
	
} );

 

Pretty standard stuff. It could be any action, executed anywhere.

Now, define the Trigger class:

/**
 * Custom trigger class
 */
class CustomTrigger extends \BracketSpace\Notification\Abstracts\Trigger {

	/**
	 * Constructor
	 */
	public function __construct() {

		// 1. Slug, can be prefixed with your plugin name.
		// 2. Title, should be translatable.
		parent::__construct(
			'myplugin/custom_trigger',
			__( 'Custom Trigger title', 'textdomain' )
		);

		// 1. Action hook.
		// 2. (optional) Action priority, default: 10.
		// 3. (optional) Action args, default: 1.
		// It's the same as add_action( 'my_action_hook', 'callback', 10, 2 ) with
		// only difference - the callback is always action() method (see below).
		$this->add_action( 'my_action_hook', 10, 2 );

		// 1. Trigger group, should be translatable.
		// This is optional, Group is displayed in the Trigger select.
		$this->set_group( __( 'My Triggers', 'textdomain' ) );

		// 1. Trigger description, should be translatable.
		// This is optional, Description is displayed in the Trigger select.
		$this->set_description(
			__( 'Fires when a page with "myparam" parameter is visited', 'textdomain' )
		);

	}

	/**
	 * Assigns action callback args to object
	 * Return `false` if you want to abort the trigger execution
	 *
	 * You can use the action method arguments as usually.
	 *
	 * @return mixed void or false if no notifications should be sent
	 */
	public function action( $param, $process ) {

		/**
		 * This is a method callback hooked to the action you've added in the Constructor.
		 * 
		 * Two important things which are happening here:
		 * - $this->callback_args is a numeric array containing all the callback parameters
		 *   if you want to treat them as an array
		 * - if you want to abort Trigger execution, you must return false here
		 */
		
		// If the second parameter ($process in our action) is false then abort, no notifications will be sent.
		if ( false === $process ) {
			return false;
		}

		// We can assign any property here, whole object will be accessible in Merge Tag resolver.
		$this->param_value = $param;

	}

	/**
	 * Registers attached merge tags
	 *
	 * @return void
	 */
	public function merge_tags() {

		/**
		 * In this method you can assign any Merge Tags to the trigger.
		 *
		 * To see what Merge Tags are available go to Notification plugin's core
		 * and look in class/Defaults/MergeTag directory.
		 */

		$this->add_merge_tag( new \BracketSpace\Notification\Defaults\MergeTag\UrlTag( array(
			// Slug (required), this will be used as {parametrized_url} value.
			// Don't translate this.
			'slug'        => 'parametrized_url',
			// Name (required), should be translatable.
			'name'        => __( 'Parametrized URL', 'textdomain' ),
			// Resolver (required), this can be a closure like below or function name
			// like: 'parametrized_url_resolver' or array( $this, 'parametrized_url_resolver' ).
			'resolver'    => function( $trigger ) {
				// $this object is available here,
				// with all the properties you set in action() method.
				return add_query_arg( 'source', $trigger->param_value, site_url() );
			},
			// Description (optional), should be translatable, default: ''.
			'description' => __( 'Homepage URL with ?source= param', 'textdomain' ),
			// Example indicator (optional)
			// if true, then description will have "Example" label, default: false.
			'example'     => true,
		) ) );

    }

}

 

And at the end we have to register it:

register_trigger( new CustomTrigger() );

 

These are all actions required to register new trigger. Result in the admin:

 

 

 


 

Troubleshooting

 

Fatal error: Class ‘BracketSpace\Notification\Abstracts\Trigger’ not found

When Trigger is registered in a plugin, it may be too early to use the abstracts or functions. All you need to do is register it later, i.e. at init action:

add_action( 'init', function() {

	class CustomTrigger extends \BracketSpace\Notification\Abstracts\Trigger {
		// ...
	}

	register_trigger( new CustomTrigger() );

} );
3 people considered this helpful