Quel est le moyen préféré pour ajouter des fichiers javascript personnalisés sur le site?

J'ai déjà ajouté mes scripts, mais je voulais connaître la méthode préférée.
Je viens de mettre une <script>balise directement dans le header.phpde mon modèle.

Existe-t-il une méthode préférée pour insérer des fichiers js externes ou personnalisés?
Comment pourrais-je lier un fichier js à une seule page? (J'ai la page d'accueil en tête)

Utilisez wp_enqueue_script()dans votre thème

La réponse de base est d'utiliser wp_enqueue_script()dans un wp_enqueue_scriptscrochet pour front-end admin_enqueue_scriptspour admin. Cela pourrait ressembler à quelque chose comme ceci (qui suppose que vous appelez depuis le functions.phpfichier de votre thème ; notez comment je référence le répertoire de la feuille de style):

<?php
add_action( 'wp_enqueue_scripts', 'mysite_enqueue' );

function mysite_enqueue() {
  $ss_url = get_stylesheet_directory_uri();
  wp_enqueue_script( 'mysite-scripts', "{$ss_url}/js/mysite-scripts.js" );
}

C'est la base.

Scripts dépendants prédéfinis et multiples

Mais supposons que vous souhaitiez inclure jQuery et jQuery UI Sortable dans la liste des scripts par défaut fournis avec WordPress et que vous souhaitiez que votre script en dépende? Facile, il suffit d' inclure les deux premiers scripts en utilisant les prédéfinis poignées définies dans WordPress et pour votre script fournir un 3ème paramètre wp_enqueue_script()qui est un tableau du script utilisé par poignées chaque script, comme suit:

<?php
add_action( 'wp_enqueue_scripts', 'mysite_enqueue' );

function mysite_enqueue() {
  $ss_url = get_stylesheet_directory_uri();
  wp_enqueue_script( 'mysite-scripts', "{$ss_url}/js/mysite-scripts.js", array( 'jquery', 'jquery-ui-sortable' ) );
}

Scripts dans un plugin

Et si vous voulez le faire dans un plugin à la place? Utilisez la plugins_url()fonction pour spécifier l'URL de votre fichier Javascript:

<?php
define( 'MY_PLUGIN_VERSION', '2.0.1' );
add_action( 'wp_enqueue_scripts', 'my_plugin_enqueue' );

function my_plugin_enqueue() {
  wp_enqueue_script( 'my-script', plugins_url('/js/my-script.js',__FILE__), array('jquery','jquery-ui-sortable'), MY_PLUGIN_VERSION );
}

Versions de vos scripts

Notez également que ci - dessus, nous avons attribué à notre plug-in un numéro de version que nous lui avons transmis en tant que 4ème paramètre wp_enqueue_script(). Le numéro de version est indiqué dans le code source sous forme d'argument de requête dans l'URL du script et force le navigateur à télécharger à nouveau le fichier éventuellement mis en cache si la version est modifiée.

Charger des scripts uniquement sur les pages où cela est nécessaire

La 1ère règle de Web Performance stipule de minimiser les requêtes HTTP afin de limiter le plus possible le chargement des scripts, le cas échéant. Par exemple, si vous n'avez besoin que de votre script dans l'administrateur, limitez-le aux pages d'administration à l'aide du admin_enqueue_scriptscrochet:

<?php
define( 'MY_PLUGIN_VERSION', '2.0.1' );
add_action( 'admin_enqueue_scripts', 'my_plugin_admin_enqueue' );

function my_plugin_admin_enqueue() {
  wp_enqueue_script( 'my-script', plugins_url( '/js/my-script.js', __FILE__ ), array( 'jquery', 'jquery-ui-sortable' ), MY_PLUGIN_VERSION );
}

Chargez vos scripts dans le pied de page

Si vos scripts font partie de ceux qui doivent être chargés dans le pied de page, un cinquième paramètre wp_enqueue_script()indique à WordPress de le retarder et de le placer dans le pied de page (en supposant que votre thème ne se soit pas mal comporté et qu'il appelle effectivement le hook wp_footer comme tout le monde). bons thèmes WordPress devraient ):

<?php
define( 'MY_PLUGIN_VERSION', '2.0.1' );
add_action( 'admin_enqueue_scripts', 'my_plugin_admin_enqueue' );

function my_plugin_admin_enqueue() {
  wp_enqueue_script( 'my-script', plugins_url( '/js/my-script.js', __FILE__ ), array( 'jquery', 'jquery-ui-sortable' ), MY_PLUGIN_VERSION, true );
}

Contrôle plus fin du grain

Si vous avez besoin d'un contrôle plus précis que cela, Ozh a publié un article intitulé Comment: charger du code JavaScript avec votre plug - in WordPress, qui détaille davantage.

Désactiver les scripts pour prendre le contrôle

Justin Tadlock a un bel article intitulé Comment désactiver les scripts et les styles au cas où vous souhaiteriez:

1. Combinez plusieurs fichiers en un seul fichier (le kilométrage peut varier avec JavaScript ici).
2. Chargez les fichiers uniquement sur les pages que nous utilisons le script ou le style.
3. Ne plus avoir à utiliser! Important dans notre fichier style.css pour effectuer de simples ajustements CSS.

Passer des valeurs de PHP à JS avec wp_localize_script()

Sur son blog, Vladimir Prelovac a publié un excellent article intitulé " Meilleure pratique pour ajouter du code JavaScript aux plugins WordPress", dans lequel il discute de l'utilisation wp_localize_script()afin de vous permettre de définir la valeur des variables dans votre PHP côté serveur pour une utilisation ultérieure dans votre code Javascript côté client.

Contrôle vraiment fin avec grain wp_print_scripts()

Et enfin, si vous avez besoin d'un contrôle vraiment précis, vous pouvez vous pencher wp_print_scripts()sur Beer Planet dans un article intitulé Comment inclure CSS et JavaScript de manière conditionnelle et uniquement lorsque cela est nécessaire .

Epiloque

C’est à peu près tout pour les meilleures pratiques d’inclusion de fichiers Javascript avec WordPress. Si j'ai oublié quelque chose (que j'ai probablement), assurez-vous de me le faire savoir dans les commentaires afin que je puisse ajouter une mise à jour pour les futurs voyageurs.

Pour complimenter Mikes de la merveilleuse illustration de l’utilisation des files d’attente, je tiens à souligner que les scripts inclus en tant que dépendances n’ont pas besoin d’être mis en file d'attente ...

J'utiliserai l'exemple sous l' en- tête Scripts in Plugin dans la réponse de Mike.

define('MY_PLUGIN_VERSION','2.0.1');

add_action( 'wp_enqueue_scripts', 'my_plugin_enqueue_scripts' );
function my_plugin_enqueue_scripts() {
    wp_enqueue_script('jquery');
    wp_enqueue_script('jquery-ui-sortable');
    wp_enqueue_script('my-script',plugins_url('/js/my-script.js',__FILE__),array('jquery','jquery-ui-sortable'),MY_PLUGIN_VERSION);
}

Cela peut être réduit pour lire ..

define('MY_PLUGIN_VERSION','2.0.1');

add_action( 'wp_enqueue_scripts', 'my_plugin_enqueue_scripts' );
function my_plugin_enqueue_scripts() {
    wp_enqueue_script('my-script', plugins_url( '/js/my-script.js', __FILE__ ), array('jquery','jquery-ui-sortable'), MY_PLUGIN_VERSION);
}

Lorsque vous définissez des dépendances, WordPress les trouve et les met en file d'attente pour votre script. Vous n'avez donc pas besoin d'appeler de manière indépendante ces scripts.

De plus, certains d'entre vous se demandent peut-être si la définition de plusieurs dépendances peut entraîner la sortie de scripts dans le mauvais ordre, laissez-moi vous donner un exemple.

wp_enqueue_script( 'first-script', 'example/path/example_script_1.js', array('second-script','third-script') );

Si le script deux dépend du script trois (c.-à-d. Que le script trois doit être chargé en premier), cela n'a pas d'importance, WordPress déterminera les priorités de mise en file d'attente de ces scripts et les affichera dans le bon ordre. En bref, tout se règle automatiquement. pour vous par WordPress.

Pour les petits morceaux de scripts, que vous ne souhaitez peut-être pas inclure dans un fichier séparé, par exemple parce qu'ils sont générés de manière dynamique, WordPress 4.5 et d'autres offres wp_add_inline_script. Cette fonction verrouille le script sur un autre script.

Supposons, par exemple, que vous développiez un thème et que vous souhaitiez que votre client puisse insérer ses propres scripts (tels que Google Analytics ou AddThis) via la page des options. Vous pouvez ensuite utiliser wp_add_inline_scriptpour verrouiller ce script sur votre fichier js principal (disons mainjs) comme ceci:

$custom_script = get_option('my-script')
if (!empty($custom_script)) wp_add_inline_script ('mainjs', $custom_script);

Ma méthode préférée est d'obtenir de bonnes performances. Par conséquent, plutôt que d' wp_enqueue_scriptutiliser HEREDOC avec l'API Fetch pour tout charger de manière asynchrone en parallèle:

$jquery_script_path = '/wp-includes/js/jquery/jquery.js?ver=1.12.4';
$jquery_dependent_script_paths = [
  get_theme_file_uri( '/assets/js/global.js' ),
  get_theme_file_uri( '/assets/js/jquery.scrollTo.js' ),
  get_theme_file_uri( '/assets/js/skip-link-focus-fix.js' ),
  get_theme_file_uri( '/assets/js/navigation.js' )
];
$jquery_dependent_script_paths_json = json_encode($jquery_dependent_script_paths);
$inline_scripts = <<<EOD
<script>
(function () {
  'use strict';
  if (!window.fetch) return;
  /**
   * Fetch Inject v1.6.8
   * Copyright (c) 2017 Josh Habdas
   * @licence ISC
   */
  var fetchInject=function(){"use strict";const e=function(e,t,n,r,o,i,c){i=t.createElement(n),c=t.getElementsByTagName(n)[0],i.type=r.blob.type,i.appendChild(t.createTextNode(r.text)),i.onload=o(r),c?c.parentNode.insertBefore(i,c):t.head.appendChild(i)},t=function(t,n){if(!t||!Array.isArray(t))return Promise.reject(new Error("`inputs` must be an array"));if(n&&!(n instanceof Promise))return Promise.reject(new Error("`promise` must be a promise"));const r=[],o=n?[].concat(n):[],i=[];return t.forEach(e=>o.push(window.fetch(e).then(e=>{return[e.clone().text(),e.blob()]}).then(e=>{return Promise.all(e).then(e=>{r.push({text:e[0],blob:e[1]})})}))),Promise.all(o).then(()=>{return r.forEach(t=>{i.push({then:n=>{"text/css"===t.blob.type?e(window,document,"style",t,n):e(window,document,"script",t,n)}})}),Promise.all(i)})};return t}();
  fetchInject(
    $jquery_dependent_script_paths_json
  , fetchInject([
    "{$jquery_script_path}"
  ]));
})();
</script>
EOD;

Et ensuite, insérez-les dans la tête, parfois avec des styles comme celui-ci:

function wc_inline_head() {
  global $inline_scripts;
  echo "{$inline_scripts}";
  global $inline_styles;
  echo "{$inline_styles}";
}

Il en résulte une chute d'eau qui ressemble à ceci, chargeant tout en même temps mais contrôlant l'ordre d'exécution:

Remarque: Cela nécessite l'utilisation de l'API Fetch, qui n'est pas disponible dans tous les navigateurs.