Utilisation des commandes de médias de personnalisation du thème WordPress

Explication détaillée du Contrôle des médias de personnalisation du thème WordPress: Nouveau WP_Customize_Media_Control Class

Les mises à jour récentes WordPress ont changé son API. Certaines fonctions et classes sont ajoutées, d'autres sont obsolètes. Cet article traite des contrôles des médias de personnalisation de sujet. Dans les versions précédentes, ces contrôles étaient disponibles, mais uniquement dans la classe WP_Customize_Upload_Control. Nous avons maintenant découvert une nouvelle classe pour gérer les médias appelés WP_Customize_Media_Control.

Tout d'abord, je vais expliquer comment utiliser cette nouvelle classe pour gérer les contrôles multimédias dans le personnalisateur de thème. Nous présenterons ensuite un exemple de classe concrète qui étend WP_Customize_Media_Control pour permettre le contrôle des images de recadrage.

Points clés:

• Le contrôle des médias de personnalisation du thème WordPress a été mis à jour pour inclure de nouvelles fonctions et classes, y compris les classes nouvelles WP_Customize_Media_Control, ce qui permet une meilleure gestion des médias.
• WP_Customize_Media_Control peut être utilisé pour permettre à l'utilisateur de sélectionner un fichier audio accessible sur toutes les pages. Ce contrôle peut être ajouté au fichier functions.php du thème ou à un nouveau plug-in.
• WP_Customize_Media_Control peut être étendu pour ajouter plus de fonctionnalités, telles que la classe WP_Customize_Cropped_Image_Control, qui permet aux utilisateurs de sélectionner et de recadrer des images avant de les utiliser.
• Le nouveau contrôle rend le personnalisateur de thème plus polyvalent, permettant aux développeurs d'ajouter leurs propres contrôles multimédias et de récupérer la valeur la plus utile: ID médiatique. Cette classe de base peut être étendue à des contrôles plus spécifiques.

Nouvelle classe de base pour gérer les contrôles multimédias

Pourquoi introduire de nouvelles classes?

Avant la version 4.3, WordPress nous a fourni WP_Customize_Upload_Control, une classe qui gère les téléchargements de fichiers multimédias dans le personnalisateur de thème. Cependant, cette classe n'enregistre pas l'ID multimédia téléchargé, mais seulement son URL. Étant donné que l'ID est le moyen le plus courant de récupérer des informations sur les fichiers multimédias, il a été décidé de fournir une nouvelle classe WP_Customize_Media_Control.

Si vous avez l'habitude d'utiliser WP_Customize_Upload_Control, vous pouvez toujours l'utiliser sans aucun problème, car il étend maintenant la classe WP_Customize_Media_Control, assurant ainsi la compatibilité. Cependant, la mise à jour de votre code et l'utilisation de WP_Customize_Media_Control est certainement une meilleure idée.

comment utiliser ce contrôle des médias

Ce nouveau contrôle des médias est utilisé de la même manière que son prédécesseur, à l'exception des valeurs enregistrées. Puisqu'il n'est plus une URL, il ne peut pas être nettoyé de la même manière.

Pour comprendre comment utiliser ce contrôle, nous passerons en revue un exemple spécifique. Nous verrons comment amener les utilisateurs à sélectionner un fichier audio que les visiteurs peuvent écouter sur toutes les pages. Vous pouvez écrire du code dans un fichier functions.php du sujet ou dans un nouveau plug-in. Les deux sont acceptables et les deux options ont leurs propres avantages.

Notez que, comme l'API de personnalisation du sujet n'est pas l'objectif principal de cet article, je ne décrirai pas toutes les options disponibles pour les fonctions que nous appellerons ici.

Utilisation de base

Tout d'abord, nous commençons par une fonction WordPress qui sera appelée par WordPress lorsque l'utilisateur souhaite afficher le personnalisateur de thème. Cette fonction ajoutera nos éléments personnalisés à ce personnalisateur. Pour informer WordPress que nous voulons qu'il appelle notre fonction au bon moment, nous utilisons l'action customize_register.

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

Le paramètre

(nommé ici $wp_customize) est un objet représentant le personnalisateur de thème. Il contient toutes les méthodes dont vous avez besoin pour ajouter des paramètres.

Puisqu'il n'y a pas de section par défaut qui convient vraiment à l'ajout de notre son personnalisé, nous ajouterons notre propre section, simplement nommée "Sound".

<code class="language-php">$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));</code>

Comme prévu, cette méthode crée une nouvelle section appelée "Sound". Lorsque l'utilisateur l'ouvre, il verra les instructions en haut. En raison de la troisième option, cette section ne peut être vue que par des utilisateurs qui peuvent déjà modifier les options de sujet. Enfin, notez le premier paramètre avant l'option de tableau: il définit l'ID de la section, que nous devons réutiliser lorsque nous voulons ajouter un contrôle dans cette section.

Si vous ouvrez le personnalisateur de thème maintenant, vous ne verrez pas cette section. Ceci est normal: WordPress n'affiche pas la partie vide, donc pour le voir, nous devons le remplir avec au moins un contrôle.

L'API de personnalisation du thème divise le contrôle en deux parties: un contrôle d'interface utilisateur qui permet à l'utilisateur de sélectionner ou de taper les données correctes, et un paramètre qui récupère la valeur actuelle et enregistre la nouvelle valeur. Traitez les paramètres comme une interface entre le contrôle de l'interface utilisateur et la base de données.

Nous devons créer des paramètres avant de créer le contrôle.

<code class="language-php">$wp_customize->add_setting('music', array(
    'type' => 'theme_mod',
    'capability' => 'edit_theme_options',
    'sanitize_callback' => 'absint'
));</code>

Nous spécifions "musique" comme l'ID que nous définissons. Il s'agit d'une modification de thème comme indiqué dans la première option. L'option de capacité est la même que la méthode add_section(). Enfin, nous spécifions absint() comme fonction de rappel de nettoyage. Cette fonction WordPress est un raccourci vers abs(intval()) pour garantir que la valeur est un entier positif. Comme nous l'avons vu ci-dessus, WP_Customize_Media_Control stockera un ID, c'est donc exactement la fonction que nous voulons utiliser pour nettoyer les valeurs.

Nous sommes maintenant prêts à ajouter des contrôles d'interface utilisateur que les utilisateurs peuvent voir.

<code class="language-php">$wp_customize->add_control(new WP_Customize_Media_Control($wp_customize, 'music', array(
    'section' => 'sound',
    'label' => 'Music',
    'mime_type' => 'audio'
)));</code>

Pour créer l'objet WP_Customize_Media_Control, trois paramètres sont requis: l'instance de personnalisation du thème actuel, l'ID de set correspondant (nous venons de créer ci-dessus) et un tableau d'options.

L'option de section

est utilisée pour indiquer la pièce que nous voulons placer le contrôle. Nous utilisons ici les sections que nous avons créées spécifiquement à cet effet. Ensuite, nous indiquons l'étiquette du champ. Vous pouvez placer toute valeur que vous souhaitez ici.

Enfin, ici, nous fournirons aux utilisateurs un moyen de sélectionner des fichiers multimédias. Comme nous voulons qu'ils ne sélectionnent que des fichiers audio, nous spécifions l'audio comme type MIME souhaité. De cette façon, WordPress ne permettra pas de sélectionner d'autres types de fichiers.

Il s'agit de créer le contrôle. Vous pouvez maintenant ouvrir le personnalisateur de thème: vous devriez voir nos sections et nos commandes.

Plus d'options

Notez que le tableau d'options que nous offrons en tant que troisième paramètre du constructeur WP_Customize_Media_Control peut accepter plus d'options.

En plus de ses balises, vous pouvez également afficher plus d'informations sur le contrôle via l'option description. En fait, en fournissant une chaîne non vide pour l'option description, vous pouvez afficher des instructions sous l'étiquette, par exemple, décrivant où elle sera affichée.

Vous pouvez définir sa priorité via l'option priority. Ce numéro définit l'ordre dans lequel les objets doivent être affichés. Par défaut, la priorité est définie sur 10 et les objets sont affichés dans l'ordre dans lequel ils sont créés. Mais vous pouvez le changer. Par exemple, si vous créez deux objets, vous pouvez définir la priorité du premier objet sur 10 et la priorité du deuxième objet à 0: de cette façon, le deuxième objet sera affiché en premier. Cette option peut être utile si votre plugin ou votre thème fournit plusieurs contrôles qui doivent être affichés dans un ordre spécifique.

Récupérer les paramètres enregistrés

Pour récupérer les paramètres enregistrés par l'utilisateur, nous créerons une nouvelle fonction appelée echo_theme_sound(). Cette fonction sera appelée où vous souhaitez afficher dans le sujet pour afficher les balises audio correspondant aux supports sélectionnés.

Tout d'abord, n'oubliez pas que nos paramètres sont une modification du thème, donc pour récupérer sa valeur, nous devons utiliser la fonction get_theme_mod().

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

Si l'utilisateur a fait une sélection, cette variable contiendra l'ID du support sélectionné. En d'autres termes, pour vérifier si un choix a été fait, nous devons simplement vérifier si cet identifiant est différent de zéro.

<code class="language-php">$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));</code>

Pour créer une balise audio, nous utiliserons wp_audio_shortcode(), qui nécessite un paramètre: un tableau d'options qui seront en fait l'attribut de la balise.

Ce tableau doit contenir une option nommée src qui est l'URL du fichier audio. Pour récupérer cette URL, nous pouvons utiliser wp_get_attachment_url() et l'ID récupéré plus tôt. Si vous souhaitez utiliser d'autres propriétés, vous pouvez, mais pas obligatoire. Pour plus d'informations sur les propriétés disponibles, voir WordPress Codex.

Nous sommes maintenant prêts à afficher nos balises audio. Je suis ici pour l'envelopper dans une div, mais vous pouvez choisir une autre balise et un autre style. Vous pouvez même, par exemple, définir deux paramètres echo_theme_sound() et $before pour votre fonction $after pour permettre à l'utilisateur de fournir du texte affiché avant et après la balise audio.

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

Maintenant, appelez simplement la fonction echo_theme_sound() où vous voulez et profitez du résultat! Notez qu'une fois que vous avez utilisé cette fonction dans un fichier de thème, vous pouvez voir les modifications que vous avez apportées dans le personnalisateur de thème directement après avoir apporté les modifications sans rafraîchir la page.

Gérer les images recadrées

peut être étendu WP_Customize_Media_Control pour ajouter plus de fonctionnalités. Si vous avez besoin d'un exemple spécifique de quelles fonctionnalités peuvent être ajoutées comme celle-ci, vous pouvez en trouver une dans WordPress Core elle-même, en utilisant la classe WP_Customize_Cropped_Image_Control.

Comme vous l'avez deviné à partir de son nom, cela est utile lorsque vous souhaitez fournir un moyen à l'utilisateur de sélectionner et de recadrer une image avant de l'utiliser.

Ici, nous l'utiliserons pour ajouter une image de sous-titre au thème WordPress par défaut actuel (vingt-quinze). J'ai choisi de montrer cette image en haut du titre, juste au-dessus du titre du site Web, mais, encore une fois, vous pouvez le dire comme vous le souhaitez: le but de cet article est juste de montrer un exemple spécifique de la nouvelle API.

Tout d'abord, nous créons nos paramètres. Étant donné que nous stockons l'ID multimédia, ce paramètre est essentiellement le même que les balises audio ajoutées plus tôt.

<code class="language-php">$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));</code>

Ensuite, la partie intéressante: le contrôle lui-même. Comme le WP_Customize_Media_Control, le constructeur de WP_Customize_Cropped_Image_Control nécessite trois paramètres, qui sont exactement les mêmes: l'instance de personnalisation du thème, l'ID set et un tableau d'options.

<code class="language-php">$wp_customize->add_setting('music', array(
    'type' => 'theme_mod',
    'capability' => 'edit_theme_options',
    'sanitize_callback' => 'absint'
));</code>

Ici, je n'ai pas créé de nouvelle section: nous réutilisons la pièce que WordPress a déjà utilisée pour fournir les contrôles, permettant à l'utilisateur de sélectionner le titre de l'image d'arrière-plan. L'option d'étiquette est une option déjà connue et vous serez plus intéressé par deux autres options: la largeur et la hauteur.

Ces options sont utilisées pour contrôler la taille de l'image finale. L'utilisateur sélectionne l'image qu'ils souhaitent, puis un outil graphique leur permet de recadrer l'image qu'ils souhaitent. WordPress recadrera l'image en fonction de cette sélection et redimensionnera l'image recadrée à la taille que vous avez sélectionnée avec ces options.

Lorsque les utilisateurs recarent une image, les contraintes des proportions d'image sont là, et ils ne peuvent pas sélectionner une partie de l'image avec d'autres proportions. Mais cela peut changer.

En fait, cette classe offre deux autres options: flex_width et flex_height. Par défaut, les deux options sont définies sur False, et le rapport d'aspect donné par les dimensions que vous indiquez est une contrainte: l'utilisateur doit sélectionner une zone avec la même proportion.

Cependant, si vous définissez l'une des options sur true, cette contrainte sera supprimée et l'utilisateur pourra sélectionner une partie de l'image avec n'importe quelle échelle. Notez que WordPress redimensionnera toujours les résultats à la taille que vous demandez, afin qu'elle puisse se déformer.

Lorsque vous utilisez flex_width et flex_height, le rapport est important. En fait, au début, WordPress fournit aux utilisateurs une zone de culture par défaut. Cette zone correspond à la plus grande zone disponible de l'image avec l'échelle souhaitée (comme le carré maximal possible dans un rectangle). Cela nous donnera ce dont nous parlons ici la largeur et la hauteur par défaut.

Si flex_width est défini sur False, l'utilisateur ne pourra pas sélectionner des zones plus grandes que la largeur par défaut. Si vous définissez cette option sur true, cette contrainte sera annulée. La même chose peut être dite pour flex_height.

Enfin, si flex_width et flex_height sont définis sur false (leurs valeurs par défaut), et si l'utilisateur sélectionne une image exactement de la même taille que vous avez indiqué dans les options de largeur et de hauteur, l'étape de recadrage être sauté.

Notez que les images de recadrage ne modifient pas l'image d'origine: un nouveau sous-média sera créé avec l'image recadrée et le fichier d'origine reste le même. De cette façon, si vos utilisateurs ont besoin d'utiliser la même image à plusieurs endroits, ils n'ont pas à télécharger la même image plusieurs fois.

La méthode de récupération des images recadrées est similaire à la méthode que nous avons utilisée pour récupérer les sons avant: nous utilisons get_theme_mod() pour obtenir l'ID d'image et wp_get_attachment_url() pour obtenir son URL. Ensuite, nous l'affichons comme nous le voulons. Ici, j'ai choisi le moyen le plus simple de faire écho à l'image.

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

Conclusion

Avec ces nouveaux contrôles, les personnalisateurs de thème deviennent de plus en plus intéressants car il permet aux développeurs de le faire plus facilement. Maintenant, si vous avez besoin d'un contrôle multimédia dans ce personnalisateur, vous pouvez ajouter votre propre contrôle et récupérer la valeur la plus utile: ID multimédia.

La classe de base observée dans cet article peut être étendue lorsque vous avez besoin de contrôles plus spécifiques. Cela se fait à plusieurs endroits du noyau WordPress: le contrôle de l'image de recadrage s'étend WP_Customize_Media_Control, et cette classe elle-même est étendue par le contrôle utilisé par la nouvelle API d'icône du site. Ce ne sont que des exemples d'actions que vous pouvez faire avec cette API.

Vous pouvez utiliser le thème ou le plug-in pour utiliser le personnalisateur de thème. Cependant, comme il est plus pratique pour moi de fournir un petit plugin, vous pouvez en trouver un via ce lien. Il combine les exemples observés dans cet article.

(La section FAQ doit être insérée ici, et le contenu est cohérent avec la partie FAQ dans le texte d'entrée)

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!