Les types de champs

text — texte court

Pour un titre, un nom, un numéro de téléphone. Le HTML est retiré à l'enregistrement.

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

<h1><?= iron_field('hero.title') ?></h1>

textarea — texte long

Pour un paragraphe, une adresse postale, une accroche. Le HTML est retiré, les retours à la ligne sont conservés.

'text' => [
    'type'  => 'textarea',
    'label' => 'Accroche',
    'desc'  => 'Deux lignes maximum.',
],

À l'affichage, les retours à la ligne du client deviennent des balises de saut de ligne. Le texte reste à l'intérieur de la balise que vous avez écrite : contrairement à un éditeur riche, aucun paragraphe n'est injecté dans votre markup.

image

Ouvre la médiathèque native de WordPress. Le client choisit ou remplace une image, avec aperçu.

'image' => [
    'type'  => 'image',
    'label' => 'Visuel de fond',
],

<?= iron_image('hero.image', '16_9', ['class' => 'hero__bg']) ?>

Le deuxième argument est le format, choisi au moment de l'affichage et non dans le schéma. Le même champ peut donc être rendu en 16_9 sur une page et en 400x400 sur une autre.

Besoin de l'adresse seule, pour un fond CSS ou une balise Open Graph :

<div style="background-image:url(<?= iron_image_url('hero.image', '16_9') ?>)">

Les formats livrés avec le thème

4_3, 16_9, 1_1, hero_inner_hd, 600x400, 400x400, 400x300, plus les formats natifs de WordPress. Ils se modifient dans inc/theme-setup.php.

link

Trois valeurs en une : le texte du lien, son adresse, et l'ouverture dans la même fenêtre ou un nouvel onglet.

'cta' => [
    'type'  => 'link',
    'label' => 'Bouton',
],

<?= iron_link('hero.cta', ['class' => 'btn btn--primary']) ?>

La fonction produit la balise complète. Elle renvoie une chaîne vide si aucune adresse n'est renseignée, ce qui évite d'avoir à tester avant.

Si le client renseigne une adresse sans texte, l'adresse sert de libellé : mieux vaut un lien inesthétique qu'un lien invisible et non cliquable.

select — liste de choix

Pour tout ce qui pilote un rendu plutôt qu'un contenu : un alignement, une variante de couleur, un nombre de colonnes.

'align' => [
    'type'    => 'select',
    'label'   => 'Alignement du contenu',
    'default' => 'left',
    'options' => [
        'left'   => 'À gauche',
        'center' => 'Centré',
        'right'  => 'À droite',
    ],
],

<section class="hero hero--<?= iron_field('hero.align') ?>">

Une option vide est toujours proposée en tête. Sans elle, un champ jamais touché prendrait silencieusement la première valeur de la liste, et le client n'aurait aucun moyen de revenir en arrière. Si le champ est required, la validation refusera ce choix vide.

Le type fonctionne aussi comme sous-champ d'une liste répétable.

repeater — liste répétable

Une liste de lignes dont vous définissez la structure et dont le client définit le contenu et l'ordre. Elle a son chapitre.

Ajouter un type

Le registre est extensible sans toucher au moteur. Un type se greffe sur un filtre et déclare quatre comportements :

add_filter('iron_field_types', function ($types) {

    $types['color'] = [
        'label'    => 'Couleur',
        'default'  => '',
        'sanitize' => 'ma_sanitize_couleur',   // au nettoyage
        'render'   => 'ma_render_couleur',     // à la saisie
        'escape'   => 'ma_escape_couleur',     // à l'affichage
    ];

    return $types;
});

Deux clés optionnelles : label_for à false pour un type composé dont le libellé ne cible aucun contrôle précis, et is_filled pour un type dont le vide ne se détecte pas par un simple test.