Comment inclure JavaScript et CSS dans vos thèmes et plugins WordPress

Il est très important pour les concepteurs et les développeurs de savoir comment inclure les fichiers JavaScript et CSS dans vos thèmes et plug-ins WordPress. Si vous ne respectez pas les meilleures pratiques, vous risquez d'entrer en conflit avec d'autres thèmes et plug-ins, voire de créer des problèmes qui auraient pu être facilement évités. Cet article est destiné à servir de référence pour bien jouer avec d’autres.

Avant de commencer, vous pouvez parcourir nos thèmes WordPress et nos plugins WordPress si vous devez lancer votre prochain projet de manière professionnelle..

Et si, après la lecture de ce didacticiel, vous ne savez toujours pas comment inclure correctement vos fichiers JavaScript et CSS, il peut être intéressant de commander certains des services WordPress disponibles sur Envato Studio..

De l'installation à la personnalisation, en passant par l'optimisation du référencement et de la vitesse, vous pouvez faire appel à un expert WordPress professionnel pour vous aider à configurer votre système dès le début..

Les meilleures pratiques rendent tout le monde heureux

Si vous avez déjà développé un thème ou un plugin pour WordPress, ou travaillé avec un thème créé par quelqu'un d'autre, vous avez probablement rencontré plusieurs méthodes différentes pour inclure JavaScript et CSS. Bien que plusieurs méthodes puissent sembler fonctionner dans certaines circonstances, il existe une méthode principale recommandée dans le Codex WordPress. Cette méthode préférée garantira que votre thème ou votre plugin fonctionne dans tous les cas, en supposant que les autres codent également de la bonne manière..

Il y a aussi un malentendu sur ce que dit exactement le Codex à ce sujet, ce que je vais aider à clarifier..

Qu'y a-t-il dans la boite?

Lorsque vous téléchargez WordPress, une sélection de bibliothèques JavaScript courantes est déjà incluse et peut être utilisée pour votre développement JavaScript. Une liste des bibliothèques incluses peut être trouvée dans le Codex WordPress wp_enqueue_script article.

Toutes ces bibliothèques sont incluses, mais par défaut, WordPress ne charge que celles dont il a besoin et uniquement s’il en a besoin dans l’administrateur. Si vous écrivez du JavaScript qui utilise l'une de ces bibliothèques, vous devez indiquer à WordPress que votre script nécessite que la bibliothèque soit chargée en premier..

Informer WordPress de votre script et de ce dont il a besoin

Voici quelques éléments à prendre en compte lorsque vous codez JavaScript pour WordPress:

Puis-je utiliser une bibliothèque incluse??
Puis-je utiliser la version incluse?
Dois-je charger mon script dans le front-end et dans l'admin?
Quelles sont les pages frontales et administratives nécessaires pour charger mon script??

En répondant à ces questions, vous saurez ce que vous devez faire pour vous inscrire et charger votre script. Ceci est fait en utilisant une fonction WordPress appelée wp_register_script, et voici son utilisation selon le codex WordPress:

wp_register_script ($ handle, $ src, $ deps, $ ver, $ in_footer);

Alors, quelles sont ces variables et en avons-nous besoin à chaque fois? (Ceci est couvert sur la page du Codex, je vais donc être bref et utiliser un anglais simple)

$ handle - ce que vous utiliserez pour faire référence à ce script particulier chaque fois que vous aurez besoin de le mettre en file d'attente, et vous devrez au moins inclure cette variable
$ src - le chemin du fichier source dans votre plugin ou votre thème
$ deps - un tableau contenant le $ handle pour tous les autres scripts que votre script doit exécuter (c'est-à-dire une dépendance)
$ ver - le numéro de version de votre script, qui peut être utilisé pour le contournement du cache. Par défaut, WordPress utilisera son propre numéro de version comme numéro de version de votre script.
$ in_footer - voulez-vous que votre script soit chargé dans le pied de page? Définissez ceci sur vrai ou faux. Il est faux par défaut, il se charge dans l'en-tête où wp_head () est, et si vous spécifiez vrai il va charger où wp_footer () apparaît dans le thème

Qu'est-ce que "Cache-Busting"??

Les navigateurs mémorisent les scripts et les feuilles de style qu'ils ont téléchargés pour un site particulier en fonction de l'URL du script et de la feuille de style. Si vous modifiez l'URL, même en ajoutant simplement une chaîne de requête, le navigateur suppose qu'il s'agit d'un nouveau fichier et le télécharge..

Ok, essayons quelques exemples

Voici l'exemple le plus élémentaire de chargement d'un script personnalisé:

function wptuts_scripts_basic () // Enregistrez le script comme ceci pour un plugin: wp_register_script ('custom-script', plugins_url ('/js/custom-script.js', __FILE__)); // ou // Enregistrez le script comme celui-ci pour un thème: wp_register_script ('custom-script', get_template_directory_uri (). '/js/custom-script.js'); // Pour un plugin ou un thème, vous pouvez ensuite mettre en file d'attente le script: wp_enqueue_script ('custom-script');  add_action ('wp_enqueue_scripts', 'wptuts_scripts_basic');

Premièrement, nous enregistrons le script afin que WordPress sache de quoi nous parlons. La manière de trouver le chemin d'accès à notre fichier JavaScript est différente si nous codons un plugin ou un thème, c'est pourquoi j'ai inclus des exemples des deux ci-dessus. Ensuite, nous le mettons en file d'attente pour être ajouté au code HTML de la page lorsqu'elle est générée, par défaut dans le où le wp_head () est dans le thème.

Le résultat de cet exemple de base est le suivant:

Désormais, si votre script repose sur l’une des bibliothèques incluses dans WordPress, telle que jQuery, vous pouvez apporter une modification très simple au code:

function wptuts_scripts_with_jquery () // Enregistrez le script comme ceci pour un plugin: wp_register_script ('custom-script', plugins_url ('/js/custom-script.js', __FILE__), array ('jquery')); // ou // Enregistrez le script comme ceci pour un thème: wp_register_script ('custom-script', get_template_directory_uri (). '' /js/custom-script.js ', array (' jquery ')); // Pour un plugin ou un thème, vous pouvez ensuite mettre en file d'attente le script: wp_enqueue_script ('custom-script');  add_action ('wp_enqueue_scripts', 'wptuts_scripts_with_jquery');

Remarque: Par défaut, jQuery est chargé avec noConflict pour éviter les conflits avec d'autres bibliothèques (telles que Prototype). Voir la section noConflict du Codex si vous ne savez pas comment vous en occuper..

Regarde ce que j'ai fait là? Vous venez d'ajouter un tableau avec le descripteur 'jquery' comme dépendance. Il utilise un tableau ici, car votre script peut avoir plusieurs dépendances. Si votre script utilise jQuery et jQuery UI, vous devez ajouter jQuery UI à votre tableau de dépendances, comme array ('jquery', 'jquery-ui-core')

Alors maintenant, la sortie a changé, et nous pouvons voir que jQuery a également été ajouté à la de la page:

Essayons un exemple avec toutes les cloches et sifflets:

function wptuts_scripts_with_the_lot () // Enregistrez le script comme ceci pour un plugin: wp_register_script ('custom-script', plugins_url ('/js/custom-script.js', __FILE__), array ('jquery', 'jquery', -core '),' 20120208 ', vrai); // ou // Enregistrez le script comme ceci pour un thème: wp_register_script ('custom-script', get_template_directory_uri (). '/js/custom-script.js', array ('jquery', 'jquery-ui-core' ), '20120208', vrai); // Pour un plugin ou un thème, vous pouvez ensuite mettre en file d'attente le script: wp_enqueue_script ('custom-script');  add_action ('wp_enqueue_scripts', 'wptuts_scripts_with_the_lot');

Ok, donc j'ai maintenant ajouté une version et spécifié que ce script doit être chargé dans le pied de page. Pour le numéro de version, j'ai choisi d'utiliser la date du jour, car il est facile de le suivre, mais vous pouvez utiliser la numérotation de version de votre choix. La sortie de celui-ci est également légèrement différente, jQuery est sorti dans le et notre script avec jQuery UI est sortie juste avant , comme ça:

… …  …

Mise en ordre de vos priorités

Certaines personnes préféreront peut-être ne pas utiliser les méthodes de mise en file d'attente appropriées, car elles estiment avoir moins de contrôle sur l'ordre de chargement des scripts. Par exemple, dans un thème qui utilise modernizr, son auteur peut vouloir s’assurer que modernizr est chargé à un stade précoce..

Quelque chose que je n'ai pas mentionné plus tôt est plus détaillée sur la add_action La fonction fonctionne, car c’est là que nous pouvons exercer un peu d’influence sur l’ordre des choses. Voici l'utilisation de la fonction selon la page WordPress Codex:

add_action ($ tag, $ function_to_add, $ priority, $ shared_args);

Notez que souvent, et jusqu’à présent dans cet article, seul le tag $ et $ function_to_add les paramètres sont utilisés. le $ priorité paramètre par défaut à 10, et le $ shared_args La valeur par défaut du paramètre est 1. Si nous voulons que nos scripts ou nos styles soient mis en file d'attente plus tôt, nous baissons simplement la valeur de $ priorité par défaut. Par exemple:

function wptuts_scripts_important () // Enregistrez le script comme ceci pour un plugin: wp_register_script ('custom-script', plugins_url ('/js/custom-script.js', __FILE__)); // ou // Enregistrez le script comme celui-ci pour un thème: wp_register_script ('custom-script', get_template_directory_uri (). '/js/custom-script.js'); // Pour un plugin ou un thème, vous pouvez ensuite mettre en file d'attente le script: wp_enqueue_script ('custom-script');  add_action ('wp_enqueue_scripts', 'wptuts_scripts_important', 5);

La sortie sera la même que celle que nous avons vue précédemment, mais elle se produira plus tôt dans le document HTML..

Remplacement de bibliothèques par défaut et utilisation de réseaux de distribution de contenu

Il peut arriver que vous souhaitiez utiliser une version différente d'une bibliothèque fournie avec WordPress. Peut-être souhaitez-vous utiliser une version de pointe ou ne pas attendre la prochaine version de WordPress avant d'utiliser la dernière version stable de jQuery. Une autre raison peut être que vous souhaitez tirer parti de la version CDN d'une bibliothèque de Google..

Il est important de noter que cela devrait seulement être fait sur des plugins ou des thèmes utilisés sur des sites que vous serez maintenir personnellement. Tous les plugins ou thèmes que vous publiez pour une utilisation publique doivent utiliser les bibliothèques incluses avec WordPress..

"Pourquoi?!", Je vous entends demander. Pour la simple raison que vous ne contrôlez pas ces sites. Vous ne savez pas quels autres plugins et thèmes pourraient être utilisés ici, et vous ne savez pas à quelle fréquence ils mettront à jour votre plugin ou votre thème. Utiliser les bibliothèques fournies avec WordPress est l'option la plus sûre.

Cela dit, si vous souhaitez le faire sur un site que vous contrôlez, voici comment procéder:

function wptuts_scripts_load_cdn () // Annule l'enregistrement de la bibliothèque incluse wp_deregister_script ('jquery'); // Enregistre à nouveau la bibliothèque à partir du CDN de Google wp_register_script ('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js', array (), null, false ) // Enregistrez le script comme ceci pour un plugin: wp_register_script ('custom-script', plugins_url ('/js/custom-script.js', __FILE__), array ('jquery')); // ou // Enregistrez le script comme ceci pour un thème: wp_register_script ('custom-script', get_template_directory_uri (). '' /js/custom-script.js ', array (' jquery ')); // Pour un plugin ou un thème, vous pouvez alors mettre en file d'attente le script: wp_enqueue_script ('custom-script');  add_action ('wp_enqueue_scripts', 'wptuts_scripts_load_cdn');

Alors tout d’abord, je désenregistre la version incluse de la bibliothèque, sinon des conflits pourraient apparaître entre différentes versions. Enregistrez ensuite la version de remplacement, en utilisant le même descripteur, et j’ai choisi de spécifier null comme version (il figure déjà dans l’URL!) Et non dans le pied de page. Le reste de notre code est identique, car nous dépendions du script qui utilisait le descripteur 'jquery'. La sortie que nous obtenons maintenant ressemble à ceci:

Remarque: L'une des raisons pour lesquelles c'est une mauvaise idée de faire dans un plugin ou un thème pour publication publique, est que tous les autres plugins et thèmes utilisés sur ce site devront maintenant utiliser cette version de jQuery. De plus, la version nouvellement enregistrée de jQuery n’a aucun ensemble noConflict. Par conséquent, si d’autres scripts de plug-in ou de thèmes utilisent Prototype, par exemple, ça va casser des choses.

Ne soyez pas gourmand

Jusqu’à présent, nous n’avons rien dit sur la façon de faire tout cela dans l’administrateur, mais seulement au début. La principale différence est quelle action utiliser. Au lieu de add_action ('wp_enqueue_scripts', 'wptuts_scripts_basic'); que nous utilisons pour le front-end, l'action pour l'administrateur est add_action ('admin_enqueue_scripts', 'wptuts_scripts_basic');

Une chose importante à faire à la fois pour le front-end et pour l’administrateur est d’être sélectif sur les pages sur lesquelles vous chargez vos scripts. Si votre plugin ou votre thème a un script qui ne fait quelque chose que sur une seule page frontale ou admin, telle que la page d'options du thème, ou peut-être une page avec un widget spécifique, vous devez simplement charger votre script sur cette page. Pas besoin d'encrasser des choses et de charger des scripts sur des pages où ils ne sont pas utilisés!

Le codex WordPress illustre parfaitement le chargement de scripts uniquement sur des pages de plug-in. Les plugins et les thèmes pouvant varier considérablement dans leur écriture, je n’entrerai pas dans les détails sur la manière de choisir les pages sur lesquelles vous chargez les scripts, mais il était important de le mentionner pour que vous en soyez conscient. vous codez.

C'est des scripts, maintenant des styles

Le processus pour les styles est presque identique à celui des scripts. Ceci est fait en utilisant une fonction WordPress appelée wp_register_style, et voici son utilisation selon le codex WordPress:

wp_register_style ($ handle, $ src, $ deps, $ ver, $ media);

Notez que la seule différence entre wp_register_script et wp_register_style est-ce au lieu d'un $ in_footer paramètre, nous avons un $ media paramètre. Ce paramètre peut être défini sur l’un des éléments suivants: 'tout', 'écran', 'ordinateur de poche', et 'impression', ou tout autre type de média reconnu par le W3C.

Voici un exemple de mise en file d'attente d'un style:

function wptuts_styles_with_the_lot () // Enregistrez le style ainsi pour un plugin: wp_register_style ('custom-style', plugins_url ('/css/custom-style.css', __FILE__), array (), '(20120208' ',' all '); // ou // Enregistrez le style comme celui-ci pour un thème: wp_register_style ('custom-style', get_template_directory_uri (). '' /css/custom-style.css ', array (),' 20120208 ',' all '); // Pour un plugin ou un thème, vous pouvez alors mettre en file d'attente le style: wp_enqueue_style ('custom-style');  add_action ('wp_enqueue_scripts', 'wptuts_styles_with_the_lot');

Ceci est un exemple assez complet, utilisant la plupart des paramètres, et le résultat obtenu ressemble à ceci:

Alors, pourquoi tout le monde ne fait-il pas déjà les choses de cette façon??

Bonne question, et l’autre question que je suppose que vous pourriez poser est la suivante: "Qu'est-ce qui vous fait penser que c’est la" bonne "façon et pas seulement votre préférence?". La réponse est essentiellement que c'est l'approche recommandée par WordPress. Il garantit que toute combinaison de plugins et de thèmes doit pouvoir fonctionner ensemble de manière joyeuse et sans doublon.

J'ai vu quelques thèmes et cadres autour de la place qui utilisent et étiquettes dans leur header.php, et même footer.php, des fichiers pour charger les scripts et les styles du thème lui-même. Il n'y a vraiment aucune raison de faire les choses de cette façon. Comme je l'ai démontré ci-dessus, il est parfaitement possible de hiérarchiser les scripts et les styles et de choisir s'ils sont chargés dans l'en-tête ou le pied de page dans le confort et la sécurité de votre ordinateur. functions.php. L'avantage est que votre thème / framework fonctionnera avec un plus large éventail d'autres thèmes de plugins / enfants.

Un exemple chargeait jQuery en utilisant le balises, qui peuvent sembler bien fonctionner, mais cela peut en fait provoquer le chargement de jQuery deux fois! Le chargement de jQuery de cette manière n'empêchera pas WordPress de charger sa version de jQuery pour d'autres plugins, car la version de WordPress est en mode noConflict par défaut, et un plugin peut le spécifier en tant que dépendance. Alors maintenant, jQuery fonctionne pour le mode noConflict et $, et probablement aussi casser n'importe quel plugin qui utilise la bibliothèque Prototype.

Conclusion

WordPress est un système fantastique, développé avec beaucoup de réflexion. S'il existe un mécanisme permettant de faire quelque chose, c'est souvent une bonne idée de l'utiliser. Lors du développement de vos plugins et de vos thèmes, essayez de vous rappeler de coder de manière réfléchie et de jouer avec les autres..

Que pensez-vous de l'utilisation de wp_enqueue_script et ses fonctions et actions associées? Connaissez-vous des exemples où cela se fait de manière incorrecte? Connaissez-vous une raison quelconque pour ne pas suivre les conseils ci-dessus?

Si vous avez besoin d'une solution clé en main, vous pouvez parcourir nos thèmes Wordpress et nos plugins Wordpress sur Envato Market..

Code