Version 8
🤸♀️ User guide
🔧
Developer
Custom Trigger
New, custom triggers can be easily registered in your plugin or theme. All you need is a simple class declaration and a function call.
The Trigger is really only a wrapper for WordPress' action(s).
Trigger class
Have a look at the example Trigger class.
1
use BracketSpace\Notification\Abstracts\Trigger as AbstractTrigger;
2
3
/**
4
* Custom trigger class
5
*/
6
class CustomTrigger extends AbstractTrigger {
7
8
/**
9
* Constructor
10
*/
11
public function __construct() {
12
13
// 1. Slug, can be prefixed with your plugin name.
14
// 2. Title, should be translatable.
15
parent::__construct(
16
'myplugin/custom_trigger',
17
__( 'Custom Trigger title', 'textdomain' )
18
);
19
20
// 1. Action hook.
21
// 2. (optional) Action priority, default: 10.
22
// 3. (optional) Action args, default: 1.
23
// It's the same as add_action( 'any_action_hook', 'callback', 10, 2 ) with
24
// only difference - the callback is always context() method (see below).
25
$this->add_action( 'any_action_hook', 10, 2 );
26
27
// 1. Trigger group, should be translatable.
28
// This is optional, Group is displayed in the Trigger select.
29
$this->set_group( __( 'My Triggers', 'textdomain' ) );
30
31
// 1. Trigger description, should be translatable.
32
// This is optional, Description is displayed in the Trigger select.
33
$this->set_description(
34
__( 'Fires when a page with "myparam" parameter is visited', 'textdomain' )
35
);
36
37
}
38
39
/**
40
* Assigns action callback args to object
41
* Return `false` if you want to abort the trigger execution
42
*
43
* You can use the action method arguments as usually.
44
*
45
* @return mixed void or false if no notifications should be sent
46
*/
47
public function context( $param_one, $param_two ) {
48
49
/**
50
* This is a method callback hooked to the action you've added in the Constructor.
51
*
52
* Two important things which are happening here:
53
* - $this->callback_args is a numeric array containing all the callback parameters
54
* if you want to treat them as an array
55
* - if you want to abort Trigger execution, you must return false here
56
*/
57
58
// If the second parameter ($process in our action) is false then abort, no carriers will be processed.
59
if ( false === $param_two ) {
60
return false;
61
}
62
63
// We can assign any property here, whole object will be accessible in Merge Tag resolver.
64
$this->param_value = $param_one;
65
66
}
67
68
/**
69
* Registers attached merge tags
70
*
71
* @return void
72
*/
73
public function merge_tags() {
74
75
/**
76
* In this method you can assign any Merge Tags to the trigger.
77
*
78
* To see what Merge Tags are available go to Notification plugin's core
79
* and look in class/Defaults/MergeTag directory.
80
*/
81
82
$this->add_merge_tag( new \BracketSpace\Notification\Defaults\MergeTag\StringTag( [
83
// Slug (required), this will be used as {parametrized_url} value.
84
// Don't translate this.
85
'slug' => 'parametrized_url',
86
// Name (required), should be translatable.
87
'name' => __( 'Parametrized URL', 'textdomain' ),
88
// Resolver (required), this can be a closure like below or function name
89
// like: 'parametrized_url_resolver' or array( $this, 'parametrized_url_resolver' ).
90
'resolver' => function( $trigger ) {
91
// Trigger object is available here,
92
// with all the properties you set in action() method.
93
return add_query_arg( 'source', $trigger->param_value, site_url() );
94
},
95
// Description (optional), should be translatable, default: ''.
96
'description' => __( 'Homepage URL with ?source= param', 'textdomain' ),
97
// Example indicator (optional)
98
// if true, then description will have "Example" label, default: false.
99
'example' => true,
100
] ) );
101
102
}
103
104
}
Copied!
Lazy loading Trigger params
When the Trigger is registered or defined, it's too early to pull data of WordPress components like Post Types or Taxonomies. In such case, you can lazy load the name, description and group - these get's evaluated only for the editing purposes.
Instead of defining all the params in constructor, create getter methods. An example for Post Trigger:
1
use BracketSpace\Notification\Abstracts\Trigger as AbstractTrigger;
2
3
/**
4
* Custom trigger class
5
*/
6
class CustomTrigger extends AbstractTrigger {
7
8
/**
9
* Post Type slug
10
*
11
* @var string
12
*/
13
public $post_type;
14
15
/**
16
* Constructor
17
*
18
* @param string $post_type optional, default: post.
19
*/
20
public function __construct( $post_type = 'post' ) {
21
$this->post_type = $post_type;
22
23
$this->add_action( 'any_action_hook', 10, 2 );
24
}
25
26
/**
27
* Lazy loads the name
28
*
29
* @return string name
30
*/
31
public function get_name() : string {
32
// translators: singular post name.
33
return sprintf( __( '%s trigger', 'notification' ), WpObjectHelper::get_post_type_name( $this->post_type ) );
34
}
35
36
/**
37
* Lazy loads the description
38
*
39
* @return string description
40
*/
41
public function get_description() : string {
42
return sprintf(
43
// translators: 1. singular post name, 2. post type slug.
44
__( 'Fires when %1$s (%2$s) is processed', 'notification' ),
45
WpObjectHelper::get_post_type_name( $this->post_type ),
46
$this->post_type
47
);
48
}
49
50
/**
51
* Lazy loads group name
52
*
53
* @return string|null Group name
54
*/
55
public function get_group() {
56
return WpObjectHelper::get_post_type_name( $this->post_type );
57
}
58
59
/**
60
* @return false|void False if no notifications should be sent
61
*/
62
public function context() {
63
// Context setup.
64
}
65
66
/**
67
* Registers attached merge tags
68
*
69
* @return void
70
*/
71
public function merge_tags() {
72
// Merge Tags.
73
}
74
75
}
Copied!
Registering the Trigger
Having this class is only a first step. To get the trigger registered you must create an instance of this class and pass it to the Notification plugin. The best action to do that is
notification/init1
use BracketSpace\Notification\Register;
2
3
add_action( 'notification/init', function() {
4
Register::trigger( new CustomTrigger() );
5
} );
Copied!
Copy link