29. Bedingte Logik für Entwickler | Field Forge - Benutzerdefinierte Felder, gebaut für Geschwindigkeit

Bedingte Logik steuert, welche Felder in der Admin-Oberfläche basierend auf den Werten anderer Felder sichtbar sind. Dieser Abschnitt erklärt, wie man bedingte Logik programmgesteuert einrichtet.

Struktur der bedingten Logik

Jedes Feld kann eine conditional_logic-Eigenschaft haben – ein Array von ODER-Gruppen, wobei jede Gruppe ein Array von UND-Bedingungen ist.

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' ] ],
    ],
] );

Kanonische Schemaform

Der Laufzeitevaluator liest die kanonische Form { enabled: true, rules: [...] }. Field Forge akzeptiert auch die veraltete ACF-Bare-Array-Form (nur das äußere Regel-Array) und normalisiert sie beim Speichern:

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

Der field Schlüssel innerhalb jeder Bedingung wird nach dem Feld namen (nicht Schlüssel) abgeglichen. Verwenden Sie denselben Namen, den Sie an get_field() übergeben würden.

Verfügbare Operatoren

Alle Operatoren sind zwischen PHP (FIELDFORGE_Conditional_Logic::compare()) und JS (assets/js/conditional-logic.js) gespiegelt. Halten Sie beide Listen synchron, wenn Sie einen Fork erstellen.

Operator	Beschreibung	Beispiel
`==`	Gleich (locker, string-konvertiert; für Arrays, wahr, wenn erwartet im Array)	`'value' => 'in_person'`
`!=`	Ungleich	`'value' => 'draft'`
`==contains`	Teilstring-Abgleich	`'value' => 'admin'`
`!=contains`	Inverser Teilstring-Abgleich	`'value' => 'spam'`
`==pattern`	Regex-Abgleich. Automatisches Einfügen von `/.../`, wenn keine Trennzeichen angegeben sind.	`'value' => '/^v\d+/i'`
`==empty`	Wahr, wenn der Wert null, ”, ‘0’, false oder leeres Array ist	`'value' => ''`
`!=empty`	Invers von `==empty`	`'value' => ''`
`>` `<` `>=` `<=`	Numerisch (`floatval` auf beiden Seiten)	`'value' => '50'`

Laufzeitevaluator

PHP-Seite (FIELDFORGE_Field_Renderer::render_field) führt eine erste serverseitige Auswertung durch, sodass Felder, deren Regeln falsch sind, mit style="display:none" ausgegeben werden – kein Flash aller Felder beim Laden der Seite.
JS-Seite (assets/js/conditional-logic.js) wertet bei jedem change / input Ereignis innerhalb des Metaboxes neu aus. Jede Metabox enthält eine data-fieldforge-cond-rules JSON-Karte; jedes bedingte Ziel enthält data-fieldforge-cond-target="".
Versteckter Trigger-Kurzschluss: Wenn ein Triggerfeld selbst versteckt ist (durch seine eigene bedingte Regel), zählen Bedingungen darauf als falsch. Ketten (A steuert B steuert C) kaskadieren automatisch – wenn A B versteckt, wird das JS erneut ausgeführt, bis eine Konvergenz erreicht ist, sodass auch C versteckt wird.
Erforderliches Attribut: Wenn ein Feld versteckt wird, wird jedes nachfolgende [required]-Attribut als data-fieldforge-cond-required="1" gespeichert und required wird entfernt, damit der Browser das Absenden nicht blockiert. Es wird wiederhergestellt, wenn das Feld wieder sichtbar wird.
Unterfeldbereich: v1 wertet nur Regeln auf obersten Feldern (direkte Kinder der Feldgruppe) aus. Regeln, die auf Unterfeldern innerhalb von Wiederholern / Gruppen / Flexiblen Inhalten platziert sind, werden gespeichert und durch Export/Import zurückgeführt, aber die Metabox rendert sie immer.

Programmatische Auswertung

FIELDFORGE_Conditional_Logic::evaluate( $logic, $values ) wird als derselbe Evaluator bereitgestellt, den der Renderer verwendet, sodass headless Aufrufer fragen können: "Würde dieses Feld gegebenen Werte angezeigt werden?" ohne DOM:

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

Bedingte Logik in Vorlagen

Bedingte Logik ist nur ein UI-Anliegen – sie beeinflusst nicht die get_field() Ausgabe. Ein verstecktes Feld behält weiterhin seinen gespeicherten Wert. Überprüfen Sie immer auf leere Werte in Vorlagen:

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

---