Les champs

Déclarer des champs

Un schéma décrit ce que le client a le droit de remplir — et rien de plus. Ni la mise en page, ni le format d'affichage.

Le principe

Un schéma est un fichier PHP qui retourne un tableau. Deux emplacements possibles, selon la portée de la donnée :

Emplacement	Portée	Rattachement
`pages/nom.fields.php`	Une page précise	`nom.php` cherche `nom.fields.php`
`options/nom.fields.php`	Tout le site	Découverte automatique, tous les fichiers fusionnés

La structure du tableau est identique dans les deux cas.

La structure

<?php

defined('ABSPATH') || exit;

return [

    'identifiant_du_groupe' => [
        'label'  => 'Titre affiché dans l\'administration',
        'fields' => [

            'identifiant_du_champ' => [
                'type'  => 'text',
                'label' => 'Libellé du champ',
                'desc'  => 'Aide affichée sous le champ.&#039;,
            ],

        ],
    ],

];

Deux niveaux, toujours : des groupes, qui contiennent des champs.

Les clés d'un champ

Clé	Obligatoire	Rôle
`type`	oui	`text`, `textarea`, `image`, `link`, `select` ou `repeater`
`label`	non	Libellé affiché. Déduit de l'identifiant s'il est absent
`desc`	non	Texte d'aide sous le champ
`default`	non	Valeur pré-remplie. Voir l'avertissement ci-dessous
`required`	non	Rend le champ obligatoire

Le type repeater accepte quatre clés supplémentaires, détaillées dans le chapitre qui lui est consacré.

Les règles de nommage

Les identifiants servent à construire une clé de base de données et un attribut de formulaire. Ils doivent donc :

commencer par une lettre minuscule ;
ne contenir que des minuscules, des chiffres et des tirets bas.

Donc hero, contact_form et bloc_2 sont valides ; Hero, 2_bloc et mon-champ ne le sont pas.

Une contrainte propre aux réglages globaux

Tous les fichiers de options/ sont fusionnés dans un seul écran. Les identifiants de groupe doivent donc être uniques d'un fichier à l'autre. Si deux fichiers déclarent un groupe contact, le second est ignoré et un avertissement est émis.

Ce qui se passe quand vous vous trompez

Une déclaration invalide n'est jamais fatale. Le champ ou le groupe fautif est ignoré, le reste continue de fonctionner, et le site du client ne tombe pas. Sous WP_DEBUG, l'erreur est signalée bruyamment par un avertissement PHP préfixé Ironframe —.

Situation	Conséquence
Le fichier ne retourne pas un tableau	Schéma vide, avertissement
Identifiant invalide	Groupe ou champ ignoré, avertissement
Clé `type` absente ou type inconnu	Champ ignoré, avertissement listant les types valides
Groupe sans clé `fields`, ou vide	Groupe ignoré, avertissement

C'est la raison pour laquelle il faut travailler avec WP_DEBUG activé : sans lui, ces avertissements sont muets.

Les champs obligatoires

'title' => [
    'type'     => 'text',
    'label'    => 'Titre principal',
    'required' => true,
],

Un astérisque apparaît à côté du libellé. Il n'y a pas de clé « optionnel » : c'est l'état par défaut de tout champ.

Le comportement dépend de l'état de la page, et cette distinction est délibérée :

Situation	Ce qui se passe
Page publiée, champ obligatoire vidé	La valeur précédente est conservée, la page reste en ligne, un message nomme le champ
Page en brouillon, champ obligatoire vide	Le passage en publié est refusé, la page reste en brouillon

Les sections désactivables

L'interrupteur se place sur le groupe, pas sur le champ :

'promo' => [
    'label'        => 'Bandeau de promotion',
    'toggle'       => true,
    'label_toggle' => 'Afficher le bandeau sur le site',
    'fields'       => [
        'title' => ['type' => 'text', 'label' => 'Message', 'required' => true],
        'cta'   => ['type' => 'link', 'label' => 'Bouton'],
    ],
],

Le client voit une case à cocher en haut de la section. Décochée, la section entière disparaît du site — sans que son contenu soit perdu : il est conservé en base et reviendra tel quel à la réactivation.

Clé	Défaut	Rôle
`toggle`	faux	Active l'interrupteur sur la section
`toggle_default`	vrai	État initial, tant que la page n'a jamais été enregistrée
`label_toggle`	Afficher cette section sur le site	Libellé de la case à cocher

<?php if (iron_has('promo.title')) : ?>
    <aside class="promo">
        <p><?= iron_field('promo.title') ?></p>
        <?= iron_link('promo.cta') ?>
    </aside>
<?php endif; ?>

Pour tester la section elle-même plutôt qu'un de ses champs : iron_is_enabled('promo') sur une page, iron_option_is_enabled('promo') dans les réglages du site.

Un champ obligatoire appartenant à une section masquée n'est pas exigé : on ne demande pas de remplir ce qui ne sera pas affiché.

Un exemple pris sur ce site

La page que vous lisez appartient à un site entièrement construit avec Ironframe. Voici, à l'identique, le groupe qui pilote la bannière de sa page d'accueil — surlignage du dernier mot compris :

pages/accueil.fields.php

'hero' => [
    'label'  => 'Bannière',
    'fields' => [

        'title' => [
            'type'     => 'text',
            'label'    => 'Titre',
            'required' => true,
        ],

        // Un champ `text` refuse le HTML — c'est voulu. Surligner un mot
        // passe donc par un champ à part, que le gabarit habille.
        'title_mark' => [
            'type'  => 'text',
            'label' => 'Dernier mot du titre, surligné',
            'desc'  => 'Laisser vide pour ne rien surligner.',
        ],

        'cta_primary' => [
            'type'     => 'link',
            'label'    => 'Bouton principal',
            'required' => true,
        ],

    ],
],