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\Action\Action
  2. Hook that into already created ShopMagic actions.

Creating new action class

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

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

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

Naming your action

Each action has to have its name set by 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 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 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 produce following output:

<tr class="shopmagic-field">
    <td class="shopmagic-label">
        <label for="text_field_input_0">Custom text field</label>
    </td>
    <td class="shopmagic-input">
        <input type="text" class="text_field_input" name="actions[0][_text_field]" id="text_field_input_0" value="">
    </td>
</tr>

To find all possibilities for setting up a field, review 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(Automation $automation, Event $event)

It's time to write some example code to show you our custom action alive and kicking. We would like to change customers role in WordPress to premium when ones buy our premium product from the store.

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

class ChangeCustomerRole extends \WPDesk\ShopMagic\Action\BasicAction {
    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( Automation $automation, Event $event ) {
        $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 filter which finds out what kind of product is bought currently, and the event that fires on new order and, when conditions are matched, your customer will have role changed.

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

Hook newly created action into ShopMagic

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

To do that, you will need to attach 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 new action by hooking into ShopMagic action you have to use associative array - simply pushing to the list won't work, because UI form will have no idea, where to save the action in database. The key for the array has no greater meaning, yet those must remain unique, unless you want to overwrite some actions.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us