Formulaires admin.

Elementum simplifie la création de formulaires pour les pages d'administration grâce à des macros Twig prêtes à l'emploi. Cette approche permet de gérer facilement les paramètres de configuration de votre thème ou plugin.

Définition des champs

Dans votre classe de page d'administration, utilisez la méthode addSetting() pour définir les champs de votre formulaire :

app/Admin/Pages/MyAdminPage.php

public function __construct()
{
    parent::__construct();

    $this
        ->addSetting("titre_site", "Mon Site")
        ->addSetting("couleur_principale", "#0073aa")
        ->addSetting("activer_maintenance", false);
}

Création du formulaire

Utilisez les macros Twig fournies pour générer le formulaire dans votre template :

views/admin/pages/my-admin-page.html.twig

{% import "@elementum/macros/forms.html.twig" as forms %}
{% block body %}
    <form method="post" class="elementum">
            {{ forms.csrf_nonce() }}
            {{ forms.input("Mon premier champ", "my_setting", data.my_setting) }}
            {{ forms.input("Mon deuxième champ", "my_setting_2", data.my_setting_2) }}
            {{ forms.submit("Enregistrer") }}
    </form>
{% endblock %}

Protection CSRF obligatoire

La macro csrf_nonce() est obligatoire dans tous les formulaires des pages d'administration. Elle génère automatiquement le champ nonce WordPress requis pour la vérification côté serveur. Sans elle, la soumission du formulaire sera rejetée avec une erreur 403.

Données du formulaire

La variable data est automatiquement fournie aux templates et contient les valeurs actuelles des champs. Si un champ n'a pas encore de valeur enregistrée, la valeur par défaut spécifiée dans addSetting() est utilisée.

Récupération des valeurs

Dans un contrôleur

Pour récupérer les valeurs enregistrées d'une page d'administration :

app/Controllers/MyController.php

#[Template('home')]
public function frontPage()
{
    // Récupération de la page d'administration
    $optionsPage = $this->adminPages()->getPage("mes-options");

    // Récupération de toutes les valeurs
    $options = $optionsPage->getSettingsValues();

    // Accès à une valeur spécifique avec une valeur par défaut
    $titre = $options->titre_site ?? 'Mon Site';

    return $this->render('@theme/index.html.twig', [
        'options' => $options,
        'titre' => $titre
    ]);
}

Dans un template Twig

<h1>{{ options.titre_site ?? 'Titre par défaut' }}</h1>

Traitement personnalisé des données

Pour des besoins spécifiques, vous pouvez surcharger la méthode post() de votre page d'administration :

app/Admin/Pages/MyAdminPage.php

public function post()
{
    // Réinitialisation des paramètres
    if (isset($this->post['reset'])) {
        $this->resetSettings();
        $this->addFlash('success', 'Les paramètres ont été réinitialisés.');
        return;
    }

    // Validation personnalisée
    if (empty($this->post['email_contact'])) {
        $this->addFlash('error', 'L\'email de contact est obligatoire');
        return;
    }

    // Nettoyage des données
    $this->post['titre_site'] = strip_tags($this->post['titre_site']);

    // Sauvegarde standard des champs
    foreach ($this->post as $key => $value) {
        $this->saveSetting($key, $value);
    }

    // Message de confirmation
    $this->addFlash('success', 'Les modifications ont été enregistrées avec succès.');
}

remarque

Si vous ne surchargez pas la méthode post(), Elementum se charge automatiquement d'enregistrer les valeurs des champs définis avec addSetting().

Bonnes pratiques

• Valeurs par défaut : Fournissez toujours des valeurs par défaut pertinentes