1. Home
  2. Docs
  3. Rules Developer Guide
  4. Extending Rules
  5. Actions

Actions

Defining a new action allows it to be added to rules as an action to perform if the rule criteria is met.

Actions are callback functions that perform some kind of operation on behalf of the user. Their return value does not affect the execution of the rule that they are assigned to in any way, even if the rule is assigned to a filter event. Therefore it is safe to return any value from an action callback.

When you define a new action, make sure that you prefix your action key with a unique slug to avoid potential collisions with other plugins that register similar action keys.

rules_define_action( $key, $definition );

/**
 * @param  string          (required)   $key         A unique key that identifies the action
 * @param  array|callable  (required)   $definition  The action definition
 */

For a detailed specification of the $definition, see the Definitions page.

@Example Code

/* Display Admin Notice */
rules_define_action( 'rules_display_admin_notice', array(
    'title' => 'Display Admin Notice',
    'description' => 'Display a notice in the WP admin at the top of the page.',
    'configuration' => array(
        'form' => function( $form, $values ) {
            $form->addField( 'rules_notice_type', 'choice', array(
                'label' => __( 'Message Type', 'mwp-rules' ),
                'choices' => array(
                    'Information' => 'info',
                    'Warning' => 'warning',
                    'Error' => 'error',
                    'Success' => 'success',
                ),
                'required' => true,
                'data' => isset( $values['rules_notice_type'] ) ? $values['rules_notice_type'] : 'info',
            ));
        },
    ),
    'arguments' => array(
        'message' => array(
            'label' => 'Message to display',
            'default' => 'manual',
            'required' => true,
            'configuration' => array(
                'form' => function( $form, $values ) {
                    $form->addField( 'rules_notice_message', 'text', array(
                        'label' => __( 'Message to display', 'mwp-rules' ),
                        'data' => isset( $values['rules_notice_message'] ) ? $values['rules_notice_message'] : '',
                    ));
                },
                'getArg' => function( $values ) {
                    return $values['rules_notice_message'];
                },
            )
        ),
    ),
    'callback' => function( $message, $values ) {
        if ( $message ) {
            add_action( 'admin_notices', function() use ( $message, $values ) {
                $type = isset( $values['rules_notice_type'] ) ? $values['rules_notice_type'] : 'info';
                echo "<div class=\"notice notice-{$type}\"><p>" . esc_html( $message ) . "</p></div>";
            });

            return 'Added message: ' . esc_html( $message );
        }

        return 'Message was blank. Skipping adding it.';
    },
));

In normal operating conditions, the return value of an action callback is ignored. However, if the rule is placed into debug mode, the return value of an invoked action will be json encoded and logged to the debug console for the rule. Therefore, it is highly recommended that you return execution details from your action callbacks to help with user debugging, especially if your action was not able to perform its function because of an error state.

Was this article helpful to you? Yes No 1

How can we help?