29. Logique conditionnelle pour les développeurs | Field Forge - Champs personnalisés, conçus pour la vitesse

La logique conditionnelle contrôle quels champs sont visibles dans l’administration en fonction des valeurs d’autres champs. Cette section explique comment configurer la logique conditionnelle de manière programmatique.

Structure de la logique conditionnelle

Chaque champ peut avoir une propriété conditional_logic — un tableau de groupes OU, où chaque groupe est un tableau de conditions ET.

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

Forme canonique du schéma

L’évaluateur d’exécution lit la forme canonique { enabled: true, rules: [...] }. Field Forge accepte également la forme de tableau nu héritée d’ACF (juste le tableau des règles extérieures) et la normalise lors de la sauvegarde :

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

La clé field à l’intérieur de chaque condition correspond par le nom du champ (pas la clé). Utilisez le même nom que vous passeriez à get_field().

Opérateurs disponibles

Tous les opérateurs sont reflétés entre PHP (FIELDFORGE_Conditional_Logic::compare()) et JS (assets/js/conditional-logic.js). Gardez les deux listes synchronisées si vous fork.

Opérateur	Description	Exemple
`==`	Égal (large, coercé en chaîne ; pour les tableaux, vrai si attendu est dans le tableau)	`'value' => 'in_person'`
`!=`	Pas égal	`'value' => 'draft'`
`==contains`	Correspondance de sous-chaîne	`'value' => 'admin'`
`!=contains`	Correspondance de sous-chaîne inverse	`'value' => 'spam'`
`==pattern`	Correspondance Regex. S’enveloppe automatiquement avec `/.../` si aucun délimiteur fourni.	`'value' => '/^v\d+/i'`
`==empty`	Vrai lorsque la valeur est null, ”, ‘0’, faux ou tableau vide	`'value' => ''`
`!=empty`	Inverse de `==empty`	`'value' => ''`
`>` `<` `>=` `<=`	Numérique (`floatval` des deux côtés)	`'value' => '50'`

Évaluateur d'exécution

Côté PHP (FIELDFORGE_Field_Renderer::render_field) effectue une évaluation initiale côté serveur afin que les champs dont les règles sont fausses soient émis avec style="display:none" — pas de flash de tous les champs au chargement de la page.
Côté JS (assets/js/conditional-logic.js) réévalue à chaque événement change / input à l'intérieur de la metabox. Chaque metabox porte une carte JSON data-fieldforge-cond-rules ; chaque cible conditionnelle porte data-fieldforge-cond-target="".
Court-circuit de déclencheur caché : si un champ déclencheur est lui-même caché (par sa propre règle conditionnelle), les conditions qui en dépendent comptent comme fausses. Les chaînes (A contrôle B contrôle C) se propagent automatiquement — lorsque A cache B, le JS se réexécute jusqu'à convergence, donc C se cache également.
Attribut requis : lorsqu'un champ se cache, tout attribut descendant [required] est conservé comme data-fieldforge-cond-required="1" et required est supprimé afin que le navigateur ne bloque pas la soumission. Il est restauré lorsque le champ redevient visible.
Portée des sous-champs : v1 n'évalue que les règles sur les champs de premier niveau (enfants directs du groupe de champs). Les règles placées sur des sous-champs à l'intérieur de Répétiteur / Groupe / Contenu flexible sont stockées et renvoyées par export/import mais la metabox les rend toujours.

Évaluation programmatique

FIELDFORGE_Conditional_Logic::evaluate( $logic, $values ) est exposé comme le même évaluateur que celui utilisé par le rendu, donc les appelants sans tête peuvent demander "ce champ s'afficherait-il compte tenu de ces valeurs ?" sans DOM :

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

Logique conditionnelle dans les modèles

La logique conditionnelle est une préoccupation de l'interface utilisateur uniquement — elle n'affecte pas la sortie get_field(). Un champ caché conserve toujours sa valeur stockée. Vérifiez toujours les valeurs vides dans les modèles :

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

---