1. Home
  2. Docs
  3. Rules Developer Guide
  4. Patterns & Helpers
  5. Configuration Presets

Configuration Presets

When writing definitions for your conditions and actions, a common task is to add some configuration fields which allow the user to manually select a value to use for the argument in your operation. A convenience method is available to automatically generate common form configurations for you.

MWP\Rules\Plugin::instance()->configPreset( $key, $field_name, $options )

/**
 * Configuration Form Presets
 *
 * @param   string  $key                    The key for the configuration preset to retrieve
 * @param   string  $field_name             The name of the field
 * @param   array   $options                Additional config options
 * @return  array                           The argument preset definition
 */
public function configPreset( $key, $field_name, $options=array() )

@Example Code

use MWP\Rules\Plugin as RulesPlugin;

add_action( 'rules_register_ecas', function() { 
    rules_register_condition( 'myplugin_check_username', array(
        'title' => 'Check User Name',
        'description' => 'Check the name of a user',
        'arguments' => array(
            'user' => array(
                'label' => 'User',
                'argtypes' => array( 'object' => array( 'classes' => array( 'WP_User' ) ) ),
                'required'  => true,

                /**
                 * Use the 'user' configuration preset
                 */
                'configuration' => RulesPlugin::instance()
                    ->configPreset( 'user', 'user_to_check', array( 'label' => 'User To Check' )),

            ),
            'name' => array(
                'label' => 'Name',
                'default'   => 'manual',
                'argtypes' => array( 'string' ),
                'required'  => true,

                /**
                 * Use the 'text' configuration preset
                 */
                'configuration' => RulesPlugin::instance()
                    ->configPreset( 'text', 'name_to_check', array( 'label' => 'Name To Check' )),

            ),
        ),
        'callback'  => function( $user, $name ) {
            if ( ! $user instanceof \WP_User ) {
                return FALSE;
            }

            return $user->first_name === $name;
        },
    ));
});

@Built In Presets

The following list of preset keys are available:

text (string) – A single line text entry widget
textarea (string) – A multi line text entry widget
array (array) – An array value entry widget
key_array (array) – An array key/value entry widget
datetime (object) [DateTime] – A date/time input widget
user (object) [WP_User] – A user selection widget
users (array) [WP_User] – Multiple users selection widget
post (object) [WP_Post] – A post selection widget
posts (array) [WP_Post] – Multiple post selection widget
comment (object) [WP_Comment] – A comment selection widget
comments (array) [WP_Comment] – Multiple comment selection widget
term (object) [WP_Term] – A taxonomy term selection widget
terms (array) [WP_Term] – Multiple taxonomy term select widget

@Adding Presets

You may want to create your own reusable form configurations to use in your definitions. This way when you need to refactor part of a specific form configuration, it is automatically updated for every definition that uses your preset.

Return your custom preset configuration using the rules_config_preset filter.

/**
 * Add custom preset(s)
 *
 * @param    array     $config        The existing configuration preset (if any)
 * @param    string    $key           The key of the preset requested
 * @param    string    $field_name    The name to use when creating form fields
 * @param    array     $options       Customized options to use when creating the configuration
 * @return   array
 */
function myplugin_rules_config_preset( $config, $key, $field_name, $options ) {
    switch( $key ) {
        case 'myplugin_presetname': 
            // $config = array( ... );
            break;
    }
    return $config;
}
add_filter( 'rules_config_preset', 'myplugin_rules_config_preset', 10, 4 );
Was this article helpful to you? Yes No

How can we help?