Conditions API

Conditions are the rules that decide whether an element is shown and which template applies
to a request. Oxygen ships a long list — post type, taxonomy term, user role, date, and so
on — and the Conditions API lets a plugin add its own, so a membership plugin can offer
"Membership level is Gold" as a condition alongside them.

A registered condition appears in the condition dropdown like any built-in, complete with
operands and — if you supply them — a list of values.

Registering one

add_action('oxygen_register_template_types_and_conditions', function () {
    BreakdanceConditionsAPIregister([
        'supports'  => ['element_display', 'templating'],
        'slug'      => 'myplugin-membership-level',
        'label'     => 'Membership Level',
        'category'  => 'My Plugin',
        'operands'  => ['is', 'is not'],

        'values' => function () {
            return [
                [
                    'label' => 'Levels',
                    'items' => [
                        ['text' => 'Gold',   'value' => 'gold'],
                        ['text' => 'Silver', 'value' => 'silver'],
                    ],
                ],
            ];
        },

        'callback' => function ($operand, $value) {
            $level = myplugin_current_user_level();

            if ($operand === 'is')     return $level === $value;
            if ($operand === 'is not') return $level !== $value;

            return false;
        },
    ]);
});

Register on oxygen_register_template_types_and_conditions. It fires at the point
Oxygen expects conditions to exist, on both the front end and the builder's condition
pickers.

The fields

Operands

Operands are plain strings, passed to your callback exactly as written, so any vocabulary
works. Use Oxygen's own for consistency with the built-in conditions:

is · is not · is one of · is all of · is none of · is before · is after ·
is greater than · is less than · contains · does not contain · is empty ·
is not empty

List only the ones your callback actually implements. An operand you offer and don't handle
falls through to return false, which reads to the user as a broken condition.

Values

values is a closure returning grouped options — each group has a label and a list of
items, and each item has display text and a stored value. It's a closure rather than an
array so the list is built when the picker is opened, which matters when the options come
from the database.

Omit values entirely and the user types the value instead. That's the right choice for
anything open-ended, like a numeric threshold.

allowMultiselect changes your callback's argument

With allowMultiselect off, $value is a string. With it on, $value is an array of
strings, and the callback has to handle that:

'callback' => function ($operand, $value) {
    $level = myplugin_current_user_level();

    if ($operand === 'is')     return in_array($level, $value, true);
    if ($operand === 'is not') return !in_array($level, $value, true);

    return false;
},

Getting this wrong is the most common mistake with this API, and it fails quietly —
comparing a string to an array with === is simply always false.

The callback

Return true and the condition passes: the element is shown, or the template applies. Return
false and it doesn't. The callback runs at render time with WordPress fully loaded, so
$post, get_queried_object(), wp_get_current_user() and the conditional tags are all
available.

Keep it fast. On a page with conditions on many elements, this runs many times per request.

supports

supports names where the condition may be used. The two values are:

• element_display — the condition is offered for
  element display conditions
• templating — the condition is offered for template targeting

Include both unless you have a reason not to.