How to create custom actions in ShopMagic

To create a new action in ShopMagic you are required to:

1. Create a class that implements interface \WPDesk\ShopMagic\Workflow\Action\Action
2. Hook that into already created ShopMagic actions.

Creating a new action class

In fact, to create a new action you can rely on a higher level of abstraction and extend \WPDesk\ShopMagic\Workflow\Action\Action . That abstract class holds many helpful functions and a framework for integrating the UI interface for action creation on the front end.

Additionally, you can choose to use even higher levels of abstraction from provided specified abstract classes:

• \WPDesk\ShopMagic\Workflow\Action\CustomerAction : when you want to use actions dedicated to Customers (users or guests)
• \WPDesk\ShopMagic\Workflow\Action\SendMail\AbstractSendMailAction : when you want to create an action intending to send an email message

Naming your action

Each action has to have its name set by the public function get_name() . Simply return the string (you may wrap it in __() for i18n).

Creating UI for your action

You definitely want your users to be able to select some options, write some text, or enable/disable additional features in your actions. To achieve that, you need to define an array of \WPDesk\ShopMagic\FormField\Field classes and return them in the get_fields() method. Those fields are PHP interfaces that do all the heavy lifting of writing HTML markup for you. You can find available fields in the folder vendor_prefixed/wpdesk/wp-forms/src/Field .

Adding a new text input is simple as that:

public function get_fields(): array {
    return ( new InputTextField() )
        ->set_label( 'Custom text field' ) // Here you set visible label
        ->set_name( 'text_field' ); // Name helps you save the field to database and operate on it
}

The code above will output our new field as JSON schema, transported by ShopMagic REST API to the user interface.

To find all possibilities for setting up a field, review the mentioned Field interface. You will find there such methods as set_required() , set_readonly() , and more.

Creating business logic for action

Action exists to perform some action, then the most important method is to express that capability.

1. public function execute(\WPDesk\ShopMagic\Workflow\Event\DataLayer $resources)

It's time to write some example code to show you our custom action work. We would like to change the customer's role in WordPress to premium when one buys our premium product from the store.

Let's start by creating a new class from the provided Action to have some heavy lifting done for us. (All imports are omitted in code, for a complete example refer to the file linked at the end of this section.)

class ChangeCustomerRole extends \WPDesk\ShopMagic\Workflow\Action\Action {
    public function get_name() {
        return 'Change Customer Role';
    }

    // We need to get data about Customer to make it work.
    public function get_required_data_domains() {
        return [ \WPDesk\ShopMagic\Customer\Customer::class ];
    }

    public function execute( DataLayer $resources ) {
        $customer = $this->get_customer();

        // Do it only for registered users.
        if ($customer->is_guest()) {
            return;
        }

        $user = get_user_by( 'id', $customer->get_id() );
        // Assumes, you defined the role somewhere earlier in WP.
        $user->set_role('premium-customer');
    }
}

And that's it! Add a filter that finds out what kind of product is bought currently, and the event that fires on the new order, and, when conditions are matched, your customer will have the role changed.

You can find code examples for writing a custom action on our GitHub repository.

Hook newly created action into ShopMagic

After writing code for a new action you may notice that it is not shown in available actions on the front-end yet. That's because you have to inform ShopMagic about a new action and hook it into the list of existing actions.

To do that, you will need to attach an action to shopmagic/core/actions hook. In fact, you just need to append your class to the array of actions.

add_action('shopmagic/core/actions', function ( array $actions ) {
    $actions['change_customer_role'] = new ChangeCustomerRoleAction();
    return $actions;
});

Now you are good to go and test your new action!

Worth noticing!

When adding a new action by hooking into the ShopMagic action you have to use an associative array - simply pushing to the list won't work, because the UI form will have no idea, where to save the action in the database. The key for the array has no greater meaning, yet those must remain unique unless you want to overwrite some actions.