Création d'options de thème WordPress avec l'API de personnalisation de thème

Créer des options de thème WordPress avec l'API de personnalisation de thème est facile à faire. Cet article vous montre comment c'est fait.

L'API de personnalisation de thème WordPress a été publiée avec WordPress 3.4, en 2012. Elle promettait aux développeurs un moyen standardisé d'ajouter des thèmes d'options riches et aux utilisateurs un moyen de peaufiner leur site Web de manière conviviale.

Pour les utilisateurs, le personnalisateur de thème frontal vous permet de changer rapidement l'apparence de votre site et même d'obtenir un aperçu en direct.

Le succès de ce projet est discutable, mais il est amélioré et gagne du terrain. Il a été construit sur des bases solides et il n'y a aucune raison de ne pas s'y mettre.

Voyons donc comment nous pouvons facilement ajouter des paramètres aux thèmes à l'aide de l'API.

Voici ce que nous allons couvrir aujourd'hui :

• Construire notre fondation
• Les composants d'un paramètre de thème
• Utilisation des valeurs de réglage
• Aperçus en direct
• Encapsuler dans une classe
• Autres options

Construire notre fondation

La clé de l'API de personnalisation est la classe WP_Customize_Manager , accessible via l'objet $wp_customize . Nous utiliserons diverses méthodes définies dans cette classe pour y ajouter des sections de paramètres et des contrôles.

La méthode recommandée pour créer des paramètres de thème consiste à les encapsuler dans une classe. Dans nos exemples initiaux, je n'adhérerai pas à cette recommandation pour m'assurer qu'il est clair ce qui fait partie de l'API de personnalisation et ce qui ne l'est pas. Je complèterai l'article avec une implémentation basée sur les classes.

Commençons par créer une fonction dans le fichier functions.php de notre thème, qui nous permettra d'inclure nos ajouts dans le customiseur. Cette fonction doit être accrochée à customize_register.

Les composants d'un paramètre de thème

Comme mentionné dans l'exemple, chaque élément que vous ajoutez au personnalisateur se compose de trois parties :

• Une section doit être créée pour le placer. Cette section peut être l'une des préexistantes bien sûr
• Un paramètre doit être enregistré dans la base de données, et
• Un contrôle doit être créé qui est utilisé pour manipuler le paramètre défini

Si la séparation entre un contrôle et un paramètre semble déroutante, pensez-y comme ceci : lorsque vous créez un paramètre, vous dites à WordPress qu'il existe effectivement un paramètre pour la couleur de la police et que la valeur par défaut est #444444. En soi, cela signifie déjà que ce paramètre peut être utilisé.

Cependant, le personnalisateur de thème doit savoir comment manipuler ce paramètre. Vous pouvez créer un champ de texte pour celui-ci dans lequel l'utilisateur entre manuellement de nouvelles couleurs sous la forme "#ff9900", mais vous pouvez également spécifier un contrôle de couleur, qui générerait un sélecteur de couleur. Au niveau de la base de données, tout se résumera toujours à une couleur hexadécimale, mais le côté utilisateur est différent.

Créer une rubrique

Le add_section() est utilisé pour créer des sections. Il prend deux paramètres, un slug de section et un tableau d'arguments. Voici un exemple de la façon dont j'ai configuré une section pour les options de pied de page dans un thème.

La plupart de cela est assez explicite. Notez la priorité, cependant! Ceci détermine l'ordre de la section sur l'écran. J'aime incrémenter mes options par dizaines. Si j'ai besoin d'insérer une section entre deux sections existantes, je n'aurai pas besoin de tout réindexer, je peux simplement attribuer la nouvelle 95.

Notez que les sections ne s'afficheront pas lorsqu'elles seront vides. Vous devez leur ajouter un paramètre et un contrôle avant qu'ils ne s'affichent.

Ajout de paramètres

Les paramètres sont créés avec la méthode add_setting() . Eux aussi prennent un slug comme premier paramètre et un tableau d'arguments comme second. Jetez un œil ci-dessous pour un exemple d'ajout d'une couleur d'arrière-plan à notre section ci-dessus.

Il y a un tas d'options que nous pourrions ajouter ici, mais pour l'instant, cela ira très bien. Notez que les paramètres ne sont pas liés à la section. Comme je l'ai mentionné, les paramètres sont simplement enregistrés auprès de WordPress. C'est aux contrôles, qui sont liés aux sections, de les manipuler.

Création d'un contrôle

Les contrôles sont mis en place avec la méthode add_control() . Cette méthode prend un slug et un tableau d'arguments ou peut également recevoir un objet de contrôle dédié. Un objet de contrôle est utilisé pour des contrôles plus complexes tels que des sélecteurs de couleurs ou des téléchargeurs de fichiers.

Voici comment j'ai créé le contrôle qui modifie la couleur de fond du pied de page :

J'ai passé un objet de contrôle à la méthode add_control() . Cet objet doit être construit en passant l'objet $wp_customize comme premier paramètre, un ID unique pour le contrôle comme deuxième et un tableau d'arguments comme troisième.

Notez que le contrôle est l'endroit où tout se réunit. section est défini sur l'identifiant de la section que nous avons créée et settings est défini sur l'identifiant du paramètre.

Une fois que les trois ont été configurés, vous devriez pouvoir recharger le personnalisateur et voir votre travail.

Utilisation des valeurs de réglage

Par défaut, les paramètres sont enregistrés dans un theme_mod. Theme_mods est une alternative à l'API Settings, ils offrent un moyen simple de gérer les paramètres spécifiques au thème. Tout ce que vous avez à faire pour récupérer la valeur d'un paramètre est d'utiliser la fonction get_theme_mod() avec l'identifiant du paramètre qui lui est passé.

Ajoutons du CSS dynamique à notre site Web en nous connectant à wp_head et en utilisant notre paramètre enregistré :

Aperçus en direct

Les aperçus en direct des paramètres ne sont pas activés par défaut. Pour les utiliser, vous devez faire trois choses :

• Mettre en file d'attente un fichier Javascript qui gère les aperçus
• Ajoutez la prise en charge de l'aperçu en direct pour le réglage, et
• Créez le code Javascript pour prendre soin de chaque paramètre

Mise en file d'attente du script d'aperçu en direct

La seule chose irrégulière à propos de cette étape est que nous devons utiliser le customize_preview_init et nous devons nous assurer que 'jquery' et 'customize-preview' sont chargés avant notre script. En dehors de cela, il s'agit d'une mise en file d'attente standard pointant vers un fichier javascript dans notre thème :

Ajouter la prise en charge de l'aperçu en direct pour le réglage

Celui-ci est assez simple. Dans les arguments de nos paramètres, nous devons définir une clé de transport et définir sa valeur sur postMessage . Révisons notre code d'avant :

Créez le code Javascript pour prendre soin de chaque paramètre

Nous devrons utiliser la fonction wp.customize() en Javascript. Cette fonction doit recevoir l'identifiant du paramètre comme premier paramètre, le second est une fonction de rappel. À l'intérieur, nous associons une fonction au changement de paramètre et écrivons notre code qui s'occupera du changement.

De tout ce dont nous n'avons besoin que d'écrire une ligne, utilisez ce modèle de copier-coller pour la vitesse d'écriture de l'aperçu en direct :

Encapsuler dans une classe

L'encapsulation dans une classe est une bonne idée car elle vous permet d'écrire de meilleurs noms de fonctions et de rendre votre code plus compatible avec plusieurs thèmes, si vous avez plusieurs thèmes en préparation. Voici comment je l'ai fait pour notre exemple ci-dessus.

Notez que tout est exactement le même, tout ce qui a changé est le nom de certaines fonctions et nous faisons référence à des méthodes à l'intérieur de la classe au lieu de fonctions éparpillées dans notre fichier functions.php .

Autres options

Je recommande fortement de lire la documentation sur l'API de personnalisation de thème dans le WordPress Codex. Il contient de nombreux paramètres supplémentaires et des façons de travailler avec l'API.

• thèmes gratuits
• thèmes premium