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

getSettingLink()

• 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)