Aller au contenu principal
Version: 26.0.8.7

Options personnalisées

Les options personnalisées vous permettent d'étendre les fonctionnalités natives d'Elementum en créant vos propres types de champs personnalisés dans le Customizer WordPress.

Création d'une option personnalisée​

Pour créer une nouvelle option personnalisée, utilisez la commande Dobby :

php dobby make:customize:field MyCustomField

Cette commande génère un fichier dans app/Customize/MyCustomField.php avec la structure de base suivante :

<?php

namespace Elementum\App\Customize;

use Elementum\Services\Customize\Appareance;
use Elementum\Services\Customize\Field;
use WP_Customize_Manager;
use WP_Customize_Control;
use Elementum\Services\Customize\Traits\FieldHelper;

class MyCustomField extends WP_Customize_Control
{
    use FieldHelper;

    public function __construct(WP_Customize_Manager $manager, string $id, array $args = [])
    {
        parent::__construct($manager, $id, $args);
    }

    public function render_content()
    {
        ?>
        <label for="<?= $this->getId() ?>" style="margin-bottom:0.5rem;display:inline-block;">
            <strong><?= $this->label ?></strong>
        </label>
        <input type="text" <?= $this->getDefaultAttributes() ?> />
        <?php
    }

    public static function register(Appareance $appareance)
    {
        $appareance->registerCallbackFields('votre_type', function (Field $field) {
            $field->addSetting();
            $controlInstance = new self($field->manager, $field->id, $field->controls);
            $field->manager->add_control($controlInstance);
            $field->addIcon(); // Optionnel
        });
    }
}

Structure de la classe​

Constructeur​

Le constructeur initialise le contrôle personnalisé. Appelez toujours le constructeur parent avec parent::__construct().

Méthode render_content()​

Cette méthode définit le rendu final HTML de votre contrôle côté client. Utilisez les méthodes du trait FieldHelper pour faciliter la création des champs.

Méthode statique register()​

Cette méthode est appelée pour enregistrer le type de champ personnalisé. Elle définit comment le champ doit être instancié et ajouté au gestionnaire du Customizer.

Intégration avec React​

Pour des interfaces plus dynamiques, vous pouvez créer un composant React personnalisé.

  1. Créez votre composant dans assets/src/Customize/MyCustomField/main.jsx
  2. Assurez-vous d'utiliser le hook useInput pour la gestion des états
import { useInput } from "@/src/Hooks/useInput";
import { createRoot } from "react-dom/client";

const MyCustomFieldComponent = ({ id, label, value, className }) => {
    const triggerInput = useInput(id);

    const handleChange = (e) => {
        triggerInput((input) => (input.value = e.target.value));
    };

    return (
        <div className={`custom-field ${className || ""}`}>
            {label && <label htmlFor={id}>{label}</label>}
            <input
                type="text"
                id={id}
                value={value || ""}
                onChange={handleChange}
                className="regular-text"
            />
        </div>
    );
};

const roots = document.querySelectorAll(".my-custom-field");
if (roots) {
    roots.forEach((root) => {
        const rootElement = createRoot(root);
        const attributes = root.dataset;
        rootElement.render(<App {...attributes} />);
});

Méthodes utilitaires (FieldHelper)​

Le trait FieldHelper fournit plusieurs méthodes utiles :

getId()​

  • Retourne : string
  • Description : Récupère l'identifiant unique du champ
  • Retourne : string
  • Description : Génère l'attribut data-customize-setting-link

getDefaultAttributes()​

  • Retourne : string
  • Description : Retourne les attributs HTML de base (id, name, data-customize-setting-link)