08 ‐ Les helpers

Vue d'ensemble

Les helpers sont des fonctions namespacées sous :

BEA\Theme\Framework\Helpers\Formatting\

Import recommandé :

use function BEA\Theme\Framework\Helpers\Formatting\Image\the_image;

Tu peux aussi utiliser le nom pleinement qualifié si besoin.

---

Helper Image (Helpers\Formatting\Image)

Ce helper repose sur wp_get_attachment_image() pour afficher une image d'attachement, avec :

• attributs personnalisables
• wrappers HTML optionnels (before / after)
• filtres pour les attributs, settings et markup final

Exemple : image mise en avant dans une card

use function BEA\Theme\Framework\Helpers\Formatting\Image\the_image;

// Without ARI default image (hidden if no image)
the_image(
	(int) get_post_thumbnail_id(),
	[
		'class'         => 'card__image',
		'data-location' => 'archive-card',
	],
	[
		'before' => '<figure class="card__media">',
		'after'  => '</figure>',
	]
);

// With ARI default image
the_image(
	(int) get_post_thumbnail_id(),
	[
		'class'         => 'card__image',
		'data-location' => 'archive-card',
	],
	[
		'default' => true,
		'before'  => '<figure class="card__media">',
		'after'   => '</figure>',
	]
);

// Without ARI plugin
the_image(
	(int) get_post_thumbnail_id(),
	[
		'class' => 'card__image',
	],
	[
		'size'   => 'thumbnail',
		'before' => '<figure class="card__media">',
		'after'  => '</figure>',
	]
);

Cas d'absence d'image

Si (int) get_post_thumbnail_id() vaut 0 et 'default' => false, le helper n'affiche rien.
Avec 'default' => true, le comportement dépend de ta configuration d'image par défaut et de tes filtres.

Accessibilité : image décorative

Pour une image purement décorative, force un alt vide (alt=""), ce qui est correct en a11y :

use function BEA\Theme\Framework\Helpers\Formatting\Image\the_image;

the_image(
	$attachment_id,
	[
		'class' => 'hero__bg',
		'alt'   => '',
	],
	[
		'size' => 'full'
	]
);

Variante echo / filtres

• Variante echo : get_the_image()
• Filtres :
  • bea_theme_framework_the_image_attributes
  • bea_theme_framework_the_image_settings
  • bea_theme_framework_the_image_markup

---

Helper Link (Helpers\Formatting\Link)

Construit des liens échappés (<a>) ou des boutons en mode link (<button role="link">), avec gestion des cas target="_blank" :

• ajout automatique de rel="noopener"
• ajout d'un texte screen-reader (.sr-only) pour "nouvelle fenêtre"

Exemple : lien simple

use function BEA\Theme\Framework\Helpers\Formatting\Link\get_the_link;

echo get_the_link(
	[
		'href'  => home_url( '/contact/' ),
		'class' => 'btn btn--primary',
	],
	[
		'content' => __( 'Contact us', 'your-textdomain' ),
		'before'  => '<p class="cta">',
		'after'   => '</p>',
	]
);

Exemple : champ Link ACF

use function BEA\Theme\Framework\Helpers\Formatting\Link\the_acf_link;

$link = get_field( 'cta_link', $post_id ); // ACF link array or empty.

the_acf_link(
	[
		'field' => $link,
		'class' => 'article__cta',
	],
	[
		'before' => '<div class="article__footer">',
		'after'  => '</div>',
	]
);

Exemple : mode bouton (partage social, tracking JS)

Ce mode génère un <button> avec role="link" et un data-href (pas de href crawlable), utile pour des actions JS.

use function BEA\Theme\Framework\Helpers\Formatting\Link\the_link;

the_link(
	[
		'href'       => $share_url,
		'class'      => 'share__action',
		'target'     => '_blank',
		'aria-label' => 'Your custom attribute',
	],
	[
		'content' => __( 'Share', 'your-textdomain' ),
		'mode'    => 'button',
	]
);

Classes de navigation

get_acf_link_classes() aide a marquer :

• la page courante (current-menu-item)
• les liens externes (external-menu-item)

Variantes echo / filtres

• Variantes echo : the_link(), the_acf_link()
• Filtres :
  • bea_theme_framework_link_attributes
  • bea_theme_framework_link_settings
  • bea_theme_framework_link_markup
  • bea_theme_framework_acf_link_attribute
  • bea_theme_framework_acf_link_settings

---

Helper Share (Helpers\Formatting\Share)

Génère des actions de partage préconfigurées pour :

• facebook
• x
• linkedin
• instagram
• bluesky
• email

Chaque item utilise par défaut :

• le mode bouton du helper Link
• une icone via Helpers\Svg\get_the_icon
• un libelle screen-reader (.sr-only)

Exemple : liste de partages

use function BEA\Theme\Framework\Helpers\Formatting\Share\get_share_link;

$url   = get_permalink();
$title = get_the_title();

echo '<ul class="share">';
echo get_share_link( 'facebook', $url );
echo get_share_link(
	'x',
	$url,
	[
		'text' => $title
	],
	[],
	[
		'before' => '<li class="share__item">',
		'after'  => '</li>',
	]
);
echo '</ul>';

Variante echo / filtres

• Variante echo : the_share_link()
• Filtres :
  • bea_theme_framework_share_attributes
  • bea_theme_framework_share_settings

---

Helper Term (Helpers\Formatting\Term)

Permet de manipuler et rendre des taxonomies (WP_Term[]).

Récupérer uniquement les noms

use function BEA\Theme\Framework\Helpers\Formatting\Term\get_terms_name;

$names = get_terms_name( $terms ); // WP_Term[] -> string[]

Rendre une liste HTML

Par défaut, la sortie est de type <ul><li>...</li></ul>, avec échappement des labels.

use function BEA\Theme\Framework\Helpers\Formatting\Term\get_terms_list;

echo get_terms_list(
	get_the_terms( get_the_ID(), 'category' ) ?: [],
	[
		'before'      => '<div class="terms"><span class="terms__label">' . esc_html__( 'Categories:', 'your-textdomain' ) . '</span><ul class="terms__list">',
		'after'       => '</ul></div>',
		'before_item' => '<li>',
		'after_item'  => '</li>',
		'separator'   => '',
	]
);

Variante inline (tags)

echo get_terms_list(
	$terms,
	[
		'before'      => '<p class="tags">',
		'after'       => '</p>',
		'before_item' => '<span class="tag">',
		'after_item'  => '</span>',
		'separator'   => ', ',
	]
);

Variante echo / filtres

• Variante echo : the_terms_list()
• Filtres :
  • bea_theme_framework_term_list_attributes
  • bea_theme_framework_term_list_settings

---

Helper Text (Helpers\Formatting\Text)

Echappe et encapsule une chaine de caractères avec :

• un escape par défaut (esc_html)
• des wrappers optionnels (before / after)
• la possibilité de définir un échappement custom

Si la valeur est vide, le helper ne retourne rien.

Exemple

use function BEA\Theme\Framework\Helpers\Formatting\Text\the_text;

the_text(
	(string) get_field( 'subtitle', get_the_ID(), false ), // ACF raw string; use any string source in your project
	[
		'before' => '<p class="lead">',
		'after'  => '</p>',
		'escape' => 'wp_kses_post', // Your custom escape
	]
);

Variante echo / filtres

• Variante echo : get_the_text()
• Filtres :
  • bea_theme_framework_text_settings
  • bea_theme_framework_text_value

---

Helpers SVG (Helpers\Svg)

Permet d'insérer des icônes SVG depuis les sprites compiles dans dist/icons/ via une balise <use>.

Le cache est géré par les hashes definis dans dist/sprite-hashes.asset.php.

Fonctions disponibles

• get_the_icon( string $icon_class, $additionnal_classes = [] ) : retourne le HTML
• the_icon( string $icon_class, $additionnal_classes = [] ) : echo le HTML

Identifiants supportes

• icon-name
  Charge dist/icons/sprite.svg et cible #icon-{name}
• sprite-name/icon-name
  Charge dist/icons/{sprite-name}.svg et cible #icon-{name}

Exemple

use function BEA\Theme\Framework\Helpers\Svg\get_the_icon;
use function BEA\Theme\Framework\Helpers\Svg\the_icon;

// Return markup for concatenation or filters
$markup = get_the_icon( 'chevron-down' );

// Echo directly in a template
the_icon( 'social/facebook', [ 'share__glyph', 'u-hidden-mobile' ] );

Accessibilité SVG

Les icônes sont décoratives par défaut (aria-hidden="true", focusable="false").
Si l'icône porte une information essentielle, ajoute un texte visible ou un texte .sr-only associé.

Si le service SVG est indisponible, les helpers retournent une chaine vide.

---

Bonnes pratiques d'accessibilité (a retenir)

• Forcer alt="" pour les images décoratives.
• Ajouter un nom accessible explicite (aria-label, texte visible, ou .sr-only) pour les actions.
• Pour les liens ouvrant une nouvelle fenêtre, conserver l'indication vocale ("nouvelle fenêtre") pour les technologies d'assistance.
• Ne pas utiliser une icône seule pour transmettre une information critique sans texte associé.