Plainview Plugins

This chapter describes the action class in the SDK, which is a complement to WordPress’ actions and hooks, and convenience methods to hook into WordPress actions and filters.

The action class is best used on large projects since it requires a bit of setting up in the form of class inheritance, proper use of namespaces, etc.

Convenience methods to hook into actions and filters

The SDK offers a shorthand way of hooking into actions and filters.

The long way of hooking

add_action( 'admin_menu', array( $this, 'admin_menu' ) );
add_filter( 'test_hook', array( $this, 'test_hook' ), 10, 3 );

The SDK way of hooking

$this->add_action( 'admin_menu' );  // Calls $this->admin_menu(), default priority, default parameters.
$this->add_action( 'admin_menu', 15 );  // Priority 15 instead
$this->add_action( 'admin_menu', 100, 5 );  // Priority 100, 5 parameters.
$this->add_action( 'admin_menu', 'another_admin_menu' );  // Call $this->another_admin_menu() instead.
$this->add_action( 'admin_menu', 'another_admin_menu', 15 ); // And priority 15.
$this->add_action( 'admin_menu', 'another_admin_menu', 25, 7 ); // 7 parameters
$this->add_filter( 'test_hook', 10, 3 ); // Add to the filter test_hook, call $this->test_hook(), priority 10, 3 parameters.

Unless otherwise specified, the class method called is the name of the action / filter. After the name of the action is specified, you are free to specify either method and / or the priority and parameter count.

The WordPress SDK action class

Background

WordPress offers actions and filters. The former can only be used to inform plugins of things that are hapenning (a user logging in, a post being updated). The latter allows only one return value to be modified. The SDK actions class allows several, arbitrary, parameters to be passed and modified with a Worpdress action.

Example

In the example below, we are assuming that we have extended the \plainview\sdk\wordpress\actions\action class into our own, called example_action.

$action = new example_action();
$action->hello = true;
$action->hello2 = [];
$action->execute();

The action class will internally append a prefix and suffix and then call do_action( 'example_action', $this ).

You should now hook into the action.

$this->add_action( 'example_action' );

Now the $action can be modified. After execution is completed, you can extract the modified values from the class.

Configuration overview

Using the SDK action class entails the following steps:

1. Having your plugin’s actions in a separate namespace
2. Extending the SDK action class
3. Extending your action base class
4. Hooking into your new action.

1. Separate namespace

If you look at ThreeWP Broadcast as an example, it uses namespaces and has a separate namespace for all the actions.

\threewp_broadcast\actions

In this way your plugin can do the following:

$admin_menu = new actions\admin_menu();
$admin_menu->execute();

2. Extending the SDK action class

Once you have your own actions namespace, in it create action.php.

class action
 extends \plainview\sdk\wordpress\actions\action
{
}

In order to prevent action name conflicts, a prefix or a suffix is suggested.

public function get_prefix()
{
 return 'threewp_broadcast_';
}

When you then create an action, if will be named threewp_broadcast_NAME. The get_suffix() method does exactly as it is called, if you prefer to use suffixes.

Or both a prefix and suffix.

3. Extending your action base class

After you have a base action class that optionally uses a specific prefix and / or suffix, it is time to create a real action.

In the actions namespace, create admin_menu.php.

class admin_menu
 extends action
{
  // PROPERTIES
  // METHODS
}

The real advantage of using the WordPress SDK action class comes into play here: being able to pass several arguments to the hooks and using convenience methods that can sanitize class property manipulation.

Finally, hook into the newly-created action.

4. Hooking into your new action

We use the action methods we learned earlier.

$this->add_action( 'threewp_broadcast_admin_menu' );

public function threewp_broadcast_admin_menu( $action )
{
 if ( $action->finished() )
  return;
 $action->test = true;
 $action->finish();
}

Here we hook into the action threewp_broadcast_admin_menu, which calls the $this->threewp_broadcast_admin_menu() method with the action as the single parameter. The finish parts are explained in the heading below.


The finish methods

Since several plugins can hook into the same action, a standard way of communicating that the action has been handled by some other plugin is offered in the form of the finish methods.

$action->finish() sets the finished flag in the action.

$action->finished() is how to query the finish flag.

Note that it is up to each hook to honor the finish flag if applicable. Depending on the type action, it might make no sense to use a finish flag, such as “append a few characters to this string” actions: all plugins hooking into the action will want to append to the string.

If your action is “delete a post”, then once a hook has deleted the post it would make no sense for the other hooks to try to delete the post. Instead of each hook doing a post existence check, check if the action is finished instead.