Registering conditions (Pro) – Learn GeneratePress

Conditions decide whether a block, menu item or overlay panel is shown. GenerateBlocks Pro ships types such as location, user role and device. You can add your own type with a class that tells GenerateBlocks which rules and operators it offers and how to evaluate them.

To hook into the existing types, see Conditions: registering types and rules and Conditions: built-in rule filters.

How a condition type works

A condition type has three parts:

A type ID such as device, and a label and list of operators, set when you register the type.
Rules: the choices the editor shows for the type, as rule key => label. A device rule is mobile, a user role rule is editor.
An evaluator class that decides whether a rule, operator and value match the current request.

Register your type on the generateblocks_register_conditions action. That action fires on init at priority 10, after the built-in types.

The registry

GB Pro

GenerateBlocks_Pro_Conditions_Registry holds the registered types. Every method is static.

Method	What it does
`register( $type, $args, $classname )`	Registers a type. Returns `false` if `$type` or `$classname` is empty, the class doesn’t exist, or the class doesn’t implement `GenerateBlocks_Pro_Condition_Interface`.
`unregister( $type )`	Removes a type, including the built-in ones. Returns `false` if it isn’t registered.
`get_all()`	Returns all registered types, sorted by priority.
`get( $type )`	Returns one registered type, or `null`.
`get_instance( $type )`	Returns the evaluator object for a type, created once per request.
`evaluate( $type, $rule, $operator, $value, $context )`	Evaluates a condition. The result is cached for the rest of the request.

Arguments for register()

Argument	Description
`$type`	A unique ID for the type, for example `request_method`.
`$args['label']`	The name shown in the editor. Default: empty.
`$args['operators']`	The operators the type offers, such as `is` and `is_not`. Default: none.
`$args['priority']`	Sort order in the editor. Default: `10`. The built-in types use 10 to 110.
`$classname`	The evaluator class name.

The built-in operators are is, is_not, includes_any, includes_all, excludes_any, excludes_all, exists, not_exists, equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, before, after, between and on. The editor treats the operators you list as the choices for the type, and your evaluator gives them meaning.

Related: generateblocks_condition_types Guide: Conditions

The condition interface

GB Pro

Your evaluator class must implement GenerateBlocks_Pro_Condition_Interface. Extending GenerateBlocks_Pro_Condition_Abstract already covers two of the five methods.

Method	Description
`evaluate( $rule, $operator, $value, $context = [] )`	Returns `true` or `false`. `$rule` is the rule key, `$operator` the chosen operator, `$value` the value the user entered, and `$context` extra data such as `post_id` in a loop.
`get_rules()`	Returns the rules as `rule key => label`.
`get_rule_metadata( $rule )`	Returns an array for the rule with `needs_value` (bool) and `value_type`, and optionally `supports_multi` (bool).
`get_operators_for_rule( $rule )`	Returns the operator keys for a rule. The abstract class returns the type’s operators and removes the `includes_any`, `includes_all`, `excludes_any` and `excludes_all` operators when the rule doesn’t support multiple values.
`sanitize_value( $value, $rule )`	Returns the cleaned value. The abstract class runs `sanitize_text_field()` on it, or on each item of an array (up to 1,000 items).

value_type values used by the built-in types are none, text, number, datetime, time, day_selector, custom_field, object_selector and hierarchical_object_selector. Use none with needs_value set to false for a rule that needs no value.

Related: generateblocks_rule_metadata Guide: Conditions

The abstract class

GB Pro

GenerateBlocks_Pro_Condition_Abstract implements the interface and adds protected helpers. You still write evaluate(), get_rules() and get_rule_metadata().

Helper	Description
`get_default_rule_metadata()`	Returns `needs_value` true and `value_type` `text`.
`get_server_var( $var )`	Reads an allowed `$_SERVER` value: `HTTP_USER_AGENT`, `HTTP_REFERER`, `REQUEST_METHOD`, `REMOTE_ADDR`, `HTTP_HOST`, `REQUEST_URI` or `QUERY_STRING`. Returns an empty string for anything else.
`parse_meta_field( $rule, $value )`	For field-based types. Returns `field_name` and `comparison_value`. When the rule is `custom`, the field name comes from the value. Otherwise the rule key is the field name.
`evaluate_meta_existence()` and `evaluate_meta_value()`	Compare post, user or option meta with an operator.

Related: generateblocks_condition_rules Guide: Conditions

Example: a request method condition

GB Pro

This type shows content depending on whether the request is a GET or a POST. Put the class in its own file, and load it only once GenerateBlocks Pro is active.

class My_Plugin_Condition_Request_Method extends GenerateBlocks_Pro_Condition_Abstract {
    public function evaluate( $rule, $operator, $value, $context = [] ) {
        $method   = strtolower( $this->get_server_var( 'REQUEST_METHOD' ) );
        $is_match = $method === $rule;

        return 'is_not' === $operator ? ! $is_match : $is_match;
    }

    public function get_rules() {
        return [
            'get'  => __( 'GET request', 'my-plugin' ),
            'post' => __( 'POST request', 'my-plugin' ),
        ];
    }

    public function get_rule_metadata( $rule ) {
        return [
            'needs_value' => false,
            'value_type'  => 'none',
        ];
    }
}

Then register it on the action:

add_action( 'generateblocks_register_conditions', function() {
    if ( ! class_exists( 'My_Plugin_Condition_Request_Method' ) ) {
        require_once plugin_dir_path( __FILE__ ) . 'class-request-method-condition.php';
    }

    GenerateBlocks_Pro_Conditions_Registry::register(
        'request_method',
        [
            'label'     => __( 'Request method', 'my-plugin' ),
            'operators' => [ 'is', 'is_not' ],
            'priority'  => 120,
        ],
        'My_Plugin_Condition_Request_Method'
    );
} );

Related: generateblocks_register_conditions Guide: Conditions

Jump to

How a condition type works

The registry

The condition interface

The abstract class

Example: a request method condition