forms.media()
Intègre le composant <wp-media-picker> pour sélectionner des médias dans la bibliothèque WordPress.
Version
Cette macro est disponible depuis la version 26.0.10.0 d'Elementum.
Signature
{{ forms.media(label, name, value, options) }}
Paramètres
label
- Type :
string - Description : Le label affiché au-dessus du sélecteur de médias
- Exemple :
'Image à la une'
name (Requis)
- Type :
string - Description : Le nom du champ (attribut
name) - Exemple :
'featured_image'
value
- Type :
int|string - Description : L'ID du média sélectionné (ou URL)
- Défaut :
'' - Exemple :
42
options
- Type :
array - Description : Options de personnalisation
Options disponibles
| Option | Type | Description | Défaut |
|---|---|---|---|
class | string | Classe CSS du conteneur | "" |
input_class | string | Classe CSS de l'input | "" |
attributes | array | Attributs HTML personnalisés | [] |
help_text | string | Texte d'aide sous le sélecteur | "" |
Exemples
Sélecteur d'image simple
{{ forms.media('Image de profil', 'profile_image', '', {}) }}
Rendu HTML :
<div class="input-group"> <label for="profile_image">Image de profil</label> <wp-media-picker name="profile_image" value=""> <template slot="placeholder"> <i class="ri-file-image-line"></i> <span>Aucune image sélectionnée.</span> </template> </wp-media-picker> </div>
Sélecteur avec texte d'aide
{{ forms.media('Bannière', 'banner_image', '', { help_text: 'Dimensions recommandées : 1920x600px' }) }}
Sélecteur avec média pré-sélectionné
{{ forms.media('Logo du site', 'site_logo', theme_mods.logo_id, {}) }}
Sélecteur avec attributs personnalisés
{{ forms.media('Galerie', 'gallery_images', '', { attributes: { 'data-multiple': 'true', 'data-max-files': '10', 'data-media-type': 'image' } }) }}
Sélecteur avec classes personnalisées
{{ forms.media('Icône', 'icon', '', { class: 'custom-media-container', input_class: 'custom-media-input' }) }}
Cas d'usage
Formulaire de profil utilisateur
{% import "@elementum/macros/forms.html.twig" as forms %} <form method="post" enctype="multipart/form-data"> {{ forms.csrf_nonce() }} {{ forms.input('Nom', 'display_name', user.display_name, { required: true }) }} {{ forms.input('Bio', 'description', user.description, 'text') }} {{ forms.media('Photo de profil', 'profile_image', user.profile_image_id, { help_text: 'Image carrée recommandée (minimum 400x400px)' }) }} {{ forms.submit('Enregistrer le profil') }} </form>
Options du thème
{% import "@elementum/macros/forms.html.twig" as forms %} <form method="post" action="options.php"> {{ forms.csrf_nonce() }} <h3>Identité visuelle</h3> {{ forms.media('Logo', 'theme_logo', get_option('theme_logo_id'), { help_text: 'Format PNG ou SVG recommandé' }) }} {{ forms.media('Favicon', 'theme_favicon', get_option('theme_favicon_id'), { help_text: 'Format ICO ou PNG 32x32px' }) }} {{ forms.media('Image de partage social', 'theme_og_image', get_option('theme_og_image_id'), { help_text: '1200x630px recommandé pour Open Graph' }) }} {{ forms.submit('Enregistrer les options') }} </form>
Récupérer la valeur côté serveur
Dans un Controller Elementum
app/Controllers/SettingsController.php
use Elementum\Abstract\AdminPage; class SettingsController extends AdminPage { public function post() { // Récupérer l'ID du média $logoId = absint($_POST['logo_image'] ?? 0); // Sauvegarder l'ID update_option('theme_logo_id', $logoId); // Optionnel : récupérer l'URL $logoUrl = wp_get_attachment_url($logoId); $this->addFlash('success', 'Logo enregistré avec succès.'); } }
Structure HTML
La macro génère la structure suivante :
<div class="input-group [class]"> [si label: <label for="[name]">[label]</label>] <wp-media-picker name="[name]" value="[value]" [attributs personnalisés]> <template slot="placeholder"> <i class="ri-file-image-line"></i> <span>Aucune image sélectionnée.</span> </template> </wp-media-picker> [si help_text: <small class="form-text text-muted">[help_text]</small>] </div>