Aller au contenu principal
Version: Next

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​

OptionTypeDescriptionDéfaut
classstringClasse CSS du conteneur""
input_classstringClasse CSS de l'input""
attributesarrayAttributs HTML personnalisés[]
help_textstringTexte 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>

Voir aussi​