29. Умовна логіка для розробників | Field Forge - Кастомні поля, створені для швидкості

Умовна логіка контролює, які поля видимі в адмінці на основі значень інших полів. Цей розділ пояснює, як налаштувати умовну логіку програмно.

Структура умовної логіки

Кожне поле може мати властивість conditional_logic — масив груп OR, де кожна група є масивом умов AND.

FIELDFORGE_Field_Groups::instance()->create( [
    'title'  => 'Event Settings',
    'fields' => [
        [
            'key'   => 'field_evt_type',
            'label' => 'Event Type',
            'name'  => 'event_type',
            'type'  => 'select',
            'choices' => [ 'in_person' => 'In Person', 'virtual' => 'Virtual', 'hybrid' => 'Hybrid' ],
        ],
        [
            'key'   => 'field_evt_venue',
            'label' => 'Venue Address',
            'name'  => 'venue_address',
            'type'  => 'text',
            'conditional_logic' => [
                // Show when event_type is 'in_person' OR 'hybrid'
                [ [ 'field' => 'field_evt_type', 'operator' => '==', 'value' => 'in_person' ] ],
                [ [ 'field' => 'field_evt_type', 'operator' => '==', 'value' => 'hybrid' ] ],
            ],
        ],
        [
            'key'   => 'field_evt_url',
            'label' => 'Stream URL',
            'name'  => 'stream_url',
            'type'  => 'url',
            'conditional_logic' => [
                // Show when event_type is 'virtual' OR 'hybrid'
                [ [ 'field' => 'field_evt_type', 'operator' => '==', 'value' => 'virtual' ] ],
                [ [ 'field' => 'field_evt_type', 'operator' => '==', 'value' => 'hybrid' ] ],
            ],
        ],
        [
            'key'   => 'field_evt_capacity',
            'label' => 'Max Capacity',
            'name'  => 'max_capacity',
            'type'  => 'number',
            'conditional_logic' => [
                // Show when in_person AND has a venue address
                [
                    [ 'field' => 'field_evt_type', 'operator' => '==', 'value' => 'in_person' ],
                    [ 'field' => 'field_evt_venue', 'operator' => '!=empty', 'value' => '' ],
                ],
            ],
        ],
    ],
    'location_rules' => [
        [ [ 'param' => 'post_type', 'operator' => '==', 'value' => 'event' ] ],
    ],
] );

Канонічна форма схеми

Виконавча оцінка читає канонічну форму { enabled: true, rules: [...] }. Field Forge також приймає застарілу форму ACF у вигляді простого масиву (тільки зовнішній масив правил) і нормалізує її під час збереження:

'conditional_logic' => [
    'enabled' => true,
    'rules' => [           // outer = OR
        [                  // inner = AND
            [ 'field' => 'event_type', 'operator' => '==', 'value' => 'in_person' ],
            [ 'field' => 'venue', 'operator' => '!=empty', 'value' => '' ],
        ],
    ],
]

Ключ field всередині кожної умови співпадає за назвою поля (не за ключем). Використовуйте таку ж назву, яку ви передали б у get_field().

Доступні оператори

Всі оператори відображаються між PHP (FIELDFORGE_Conditional_Logic::compare()) та JS (assets/js/conditional-logic.js). Тримайте обидва списки в синхронізації, якщо ви форкуєте.

Оператор	Опис	Приклад
`==`	Рівно (слабке, перетворене в рядок; для масивів, істинно, якщо очікуване є в масиві)	`'value' => 'in_person'`
`!=`	Не рівно	`'value' => 'draft'`
`==contains`	Співпадіння підрядка	`'value' => 'admin'`
`!=contains`	Інверсне співпадіння підрядка	`'value' => 'spam'`
`==pattern`	Співпадіння за регулярним виразом. Автообгортка з `/.../`, якщо не надано роздільників.	`'value' => '/^v\d+/i'`
`==empty`	Істинно, коли значення є null, ”, ‘0’, false або порожній масив	`'value' => ''`
`!=empty`	Інверсія `==empty`	`'value' => ''`
`>` `<` `>=` `<=`	Числовий (`floatval` з обох сторін)	`'value' => '50'`

Оцінювач часу виконання

PHP-сторона (FIELDFORGE_Field_Renderer::render_field) проводить первинну оцінку на сервері, тому поля, правила яких є хибними, виводяться з style="display:none" — без спалаху всіх полів при завантаженні сторінки.
JS-сторона (assets/js/conditional-logic.js) переоцінює при кожній події change / input всередині метабоксу. Кожен метабокс містить JSON карту data-fieldforge-cond-rules; кожна умовна ціль має data-fieldforge-cond-target="".
Сховане тригерне коротке замикання: якщо тригерне поле само по собі приховане (за своїм власним умовним правилом), умови на ньому вважаються хибними. Ланцюги (A контролює B контролює C) автоматично каскадують — коли A приховує B, JS повторно запускається до досягнення збіжності, тому C також приховується.
Обов'язковий атрибут: коли поле приховане, будь-який нащадок атрибута [required] зберігається як data-fieldforge-cond-required="1", а required видаляється, щоб браузер не блокував відправлення. Він відновлюється, коли поле знову стає видимим.
Область підполя: v1 оцінює правила лише на первинних полях (прямі нащадки групи полів). Правила, розміщені на підполях всередині Repeater / Group / Flexible Content, зберігаються та проходять через експорт/імпорт, але метабокс завжди їх рендерить.

Програмна оцінка

FIELDFORGE_Conditional_Logic::evaluate( $logic, $values ) відкритий як той же оцінювач, який використовує рендерер, тому безголові виклики можуть запитати "чи відобразиться це поле за наявності цих значень?" без DOM:

$logic = $field['conditional_logic']; // { enabled, rules }
$values = [
    'event_type' => 'hybrid',
    'venue'      => '',
];
$visible = FIELDFORGE_Conditional_Logic::evaluate( $logic, $values );

Умовна логіка в шаблонах

Умовна логіка є лише проблемою інтерфейсу користувача — вона не впливає на вихід get_field(). Сховане поле все ще зберігає своє збережене значення. Завжди перевіряйте на порожні значення в шаблонах:

$venue = get_field( 'venue_address' );
if ( $venue ) {
    echo '<p>Venue: ' . esc_html( $venue ) . '</p>';
}

---