29. Lógica Condicional para Desarrolladores | Field Forge - Campos personalizados, diseñados para la velocidad

La lógica condicional controla qué campos son visibles en el administrador según los valores de otros campos. Esta sección explica cómo configurar la lógica condicional programáticamente.

Estructura de Lógica Condicional

Cada campo puede tener una propiedad conditional_logic — un array de grupos OR, donde cada grupo es un array de condiciones 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' ] ],
    ],
] );

Forma del esquema canónico

El evaluador en tiempo de ejecución lee la forma canónica { enabled: true, rules: [...] }. Field Forge también acepta la forma de array simple heredada de ACF (solo el array de reglas externas) y la normaliza al guardar:

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

La clave field dentro de cada condición coincide por nombre del campo (no clave). Usa el mismo nombre que pasarías a get_field().

Operadores Disponibles

Todos los operadores están reflejados entre PHP (FIELDFORGE_Conditional_Logic::compare()) y JS (assets/js/conditional-logic.js). Mantén ambas listas sincronizadas si haces un fork.

Operador	Descripción	Ejemplo
`==`	Igual (suave, coercionado a cadena; para arrays, verdadero si el esperado está en el array)	`'value' => 'in_person'`
`!=`	No igual	`'value' => 'draft'`
`==contains`	Coincidencia de subcadena	`'value' => 'admin'`
`!=contains`	Coincidencia de subcadena inversa	`'value' => 'spam'`
`==pattern`	Coincidencia de regex. Se envuelve automáticamente con `/.../` si no se proporcionan delimitadores.	`'value' => '/^v\d+/i'`
`==empty`	Verdadero cuando el valor es null, ”, ‘0’, false, o array vacío	`'value' => ''`
`!=empty`	Inverso de `==empty`	`'value' => ''`
`>` `<` `>=` `<=`	Numérico (`floatval` ambos lados)	`'value' => '50'`

Evaluador en Tiempo de Ejecución

Lado PHP (FIELDFORGE_Field_Renderer::render_field) realiza una evaluación inicial del lado del servidor, por lo que los campos cuyas reglas son falsas se emiten con style="display:none" — sin parpadeo de todos los campos al cargar la página.
Lado JS (assets/js/conditional-logic.js) reevalúa en cada evento change / input dentro del metabox. Cada metabox lleva un mapa JSON data-fieldforge-cond-rules; cada objetivo condicional lleva data-fieldforge-cond-target="".
Disparador oculto de cortocircuito: si un campo disparador está oculto (por su propia regla condicional), las condiciones sobre él cuentan como falsas. Las cadenas (A controla B controla C) se propagan automáticamente — cuando A oculta B, el JS se vuelve a ejecutar hasta la convergencia, por lo que C también se oculta.
Atributo requerido: cuando un campo se oculta, cualquier atributo descendiente [required] se guarda como data-fieldforge-cond-required="1" y required se elimina para que el navegador no bloquee el envío. Se restaura cuando el campo se vuelve visible nuevamente.
Ámbito de subcampo: v1 solo evalúa reglas en campos de nivel superior (hijos directos del grupo de campos). Las reglas colocadas en subcampos dentro de Repeater / Group / Flexible Content se almacenan y se transfieren a través de exportación/importación, pero el metabox siempre las renderiza.

Evaluación Programática

FIELDFORGE_Conditional_Logic::evaluate( $logic, $values ) se expone como el mismo evaluador que utiliza el renderizador, por lo que los llamadores sin cabeza pueden preguntar "¿se mostraría este campo dados estos valores?" sin DOM:

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

Lógica Condicional en Plantillas

La lógica condicional es solo una preocupación de UI — no afecta la salida de get_field(). Un campo oculto aún retiene su valor almacenado. Siempre verifica si hay valores vacíos en las plantillas:

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

---