Les champs
Afficher les champs
L'API de template. Six fonctions, une règle, et un garde-fou qu'il faut savoir contourner exprès.
La règle centrale
Ces fonctions retournent une valeur, elles ne l'affichent
pas. D'où la balise d'écho courte <?= dans tous les exemples.
Les fonctions
| Fonction | Ce qu'elle renvoie |
|---|---|
iron_field($chemin) |
La valeur, échappée selon son type |
iron_has($chemin) |
Vrai si le champ est rempli |
iron_image($chemin, $format, $attributs) |
Une balise image complète, avec srcset |
iron_image_url($chemin, $format) |
L'adresse seule |
iron_link($chemin, $attributs) |
Une balise de lien complète |
iron_field_raw($chemin) |
La valeur non échappée |
Toutes acceptent un dernier argument facultatif : l'identifiant d'une autre page. Par défaut, c'est la page en cours d'affichage.
Un exemple complet
<section class="hero">
<?php if (iron_has('hero.image')) : ?>
<?= iron_image('hero.image', '16_9', ['class' => 'hero__bg']) ?>
<?php endif; ?>
<h1 class="hero__title"><?= iron_field('hero.title') ?></h1>
<?php if (iron_has('hero.text')) : ?>
<p class="hero__text"><?= iron_field('hero.text') ?></p>
<?php endif; ?>
<?= iron_link('hero.cta', ['class' => 'btn']) ?>
</section>Pourquoi iron_has()
Parce qu'un champ vide ne doit pas laisser une balise vide dans le markup.
iron_image() et iron_link() savent déjà ne rien
renvoyer quand le champ est vide : le test n'est utile que lorsque vous devez
aussi éviter la balise qui les entoure.
Le chemin
Un chemin s'écrit groupe.champ, exactement comme dans le schéma.
Il n'y a pas d'autre forme, et pas de raccourci.
Quand quelque chose ne va pas
Un chemin qui n'existe pas, ou un champ lu avec la mauvaise fonction,
ne provoque jamais d'erreur fatale. La fonction renvoie une
valeur vide et, sous WP_DEBUG, émet un avertissement explicite.
| Ce que vous écrivez | Ce qui se passe |
|---|---|
| Un chemin absent du schéma | Vide, avertissement « champ inconnu » |
iron_image() sur un champ texte |
Vide, avertissement nommant les deux types |
iron_field() sur une liste répétable |
Vide, avertissement renvoyant vers iron_rows() |
Ces avertissements sont votre principal outil de débogage. Sans
WP_DEBUG, vous ne verrez qu'une page silencieusement incomplète —
et vous chercherez du côté du CSS.
L'échappement, et quand le contourner
Chaque type sait comment se rendre sûr : le texte est échappé, les retours à la ligne d'un texte long sont convertis, une adresse de lien est filtrée sur ses protocoles autorisés.
Si vous avez vraiment besoin de la valeur brute, par exemple pour la traiter vous-même avant affichage :
$valeur = iron_field_raw('hero.title');Un usage légitime, pris sur ce site
La page de contact de ce site n'affiche pas de formulaire : elle exécute le
shortcode d'une extension, déposé dans les réglages du site. Passé par
esc_html(), ce shortcode s'afficherait tel quel au lieu d'être
exécuté — c'est exactement le cas où la valeur brute est nécessaire.
// La valeur reste nettoyée à l'écriture : le type `text` retire tout le
// HTML. Ce qu'on récupère ici est du texte, qu'on confie à WordPress.
$shortcode = trim((string) iron_option_raw('contact.form_shortcode'));
if ('' !== $shortcode) {
echo do_shortcode($shortcode);
}
Le second cas classique est le retraitement d'une valeur : un numéro de
téléphone affiché avec des espaces n'en veut aucun dans un lien
tel:. On récupère le brut, on le nettoie, et
on l'échappe soi-même juste après.
$brut = preg_replace('/[^0-9+]/', '', (string) iron_option_raw('contact.phone'));
?>
<a href="<?php echo esc_url('tel:' . $brut); ?>">
<?= iron_option('contact.phone') ?>
</a>