¿Cuál es la forma preferida de agregar archivos javascript personalizados al sitio?

Usa wp_enqueue_script() en tu tema

La respuesta básica es usar wp_enqueue_script() en un gancho wp_enqueue_scripts para el front end admin_enqueue_scripts para admin . Puede parecer algo como esto (lo que supone que está llamando desde el archivo functions.php de su tema; tenga en cuenta cómo hago referencia al directorio de la hoja de estilo):

<?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" );
}

Eso es lo básico.

Scripts predefinidos y dependientes múltiples

Pero supongamos que desea incluir jQuery y jQuery UI Sortable de la lista de guiones incluidos por defecto incluidos en la lista de scripts predeterminados incluidos con WordPress > y ¿quieres que tu script dependa de ellos? Fácil, solo incluye los dos primeros scripts que utilizan los manijas predefinidos definidos en WordPress y para su script, proporcione un tercer parámetro para wp_enqueue_script() , que es una matriz de los manejadores de script utilizados por cada script, de este modo:

<?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 en un complemento

¿Qué pasa si quieres hacerlo en un plugin? Use la función plugins_url() para especificar la URL de su archivo 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 );
}

Versiones de sus scripts

También tenga en cuenta que arriba le dimos a nuestro complemento un número de versión y lo pasamos como un cuarto parámetro a wp_enqueue_script() . El número de versión se envía en la fuente como argumento de consulta en la URL a la secuencia de comandos y sirve para forzar que el navegador vuelva a descargar posiblemente el archivo en caché si la versión cambia.

Cargar scripts solo en las páginas donde sea necesario

La la primera regla del rendimiento web dice que Minimice las solicitudes HTTP , siempre que sea posible debe limitar los scripts para cargar solo donde sea necesario. Por ejemplo, si solo necesita su secuencia de comandos en el administrador, limítelo a las páginas de administración utilizando el gancho admin_enqueue_scripts en su lugar:

<?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 );
}

Cargue sus scripts en el pie de página

Si sus scripts son uno de los que deben cargarse en el pie de página, hay un quinto parámetro de wp_enqueue_script() que le dice a WordPress que lo retrase y lo coloque en el pie de página (suponiendo que su tema no se haya portado mal y que efectivamente llama al gancho wp_footer como todos los buenos temas de WordPress deben ):

<?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 );
}

Control de grano fino

Si necesita un control más preciso que el Ozh tiene un gran artículo titulado How To: Javascript con su plugin de WordPress que detalla más.

Deshabilitar scripts para obtener control

Justin Tadlock tiene un buen artículo titulado Cómo deshabilitar scripts y estilos en caso de que quieras:

1. Combine varios archivos en archivos individuales (el kilometraje puede variar con JavaScript aquí).
2. Cargue los archivos solo en las páginas en las que estamos usando el script o el estilo.
3. ¡Deje de tener que usar! important en nuestro archivo style.css para realizar ajustes CSS simples.

Pasando valores de PHP a JS con wp_localize_script()

En su blog, Vladimir Prelovac tiene un gran artículo titulado Best practica para agregar código JavaScript a los complementos de WordPress , donde analiza el uso de wp_localize_script() para permitirte establecer el valor de las variables en tu PHP del lado del servidor para que luego se use en tu Javascript del lado del cliente.

Control de grano realmente fino con wp_print_scripts()

Y, finalmente, si necesita un control realmente detallado, puede consultar wp_print_scripts() como se explica en Beer Planet en una publicación titulada Cómo incluir CSS y JavaScript condicionalmente y solo cuando sea necesario por las publicaciones .

Epiloque

Eso es todo para las Mejores Prácticas de incluir archivos Javascript con WordPress. Si me perdí algo (que probablemente tengo), asegúrese de avisarme en los comentarios para poder agregar una actualización para futuros viajeros.

Para complementar la maravillosa ilustración de Mikes sobre el uso de colas, solo deseo señalar que los scripts incluidos como dependencias no necesitan ser encolados ...

Usaré el ejemplo bajo el encabezado Secuencias de comandos en un complemento en la respuesta 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);
}

Esto se puede recortar para leer ..

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);
}

Cuando configura las dependencias, WordPress las encontrará y las pondrá en cola listas para su script, por lo que no necesita hacer llamadas independientes para estos scripts.

Además, algunos de ustedes pueden preguntarse si establecer una dependencia múltiple puede hacer que los scripts se muestren en el orden incorrecto, aquí déjeme dar un ejemplo

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

Si la secuencia de comandos dos dependía de la secuencia de comandos tres (es decir, la secuencia de comandos tres debería cargarse primero), esto no importaría, WordPress determinará las prioridades de puesta en cola para esas secuencias de comandos y las emitirá en el orden correcto. elaborado de forma automática para usted por WordPress.

Para pequeños fragmentos de scripts, que tal vez no quiera incluir en un archivo separado, por ejemplo, porque se generan dinámicamente, WordPress 4.5 y otras ofertas wp_add_inline_script . Esta función básicamente bloquea el script a otro script.

Digamos, por ejemplo, que está desarrollando un tema y desea que su cliente pueda insertar sus propios scripts (como Google Analytics o AddThis) a través de la página de opciones. Luego, podría usar wp_add_inline_script para bloquear esa secuencia de comandos en su archivo js principal (digamos mainjs ) de esta manera:

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

Mi forma preferida es lograr un buen rendimiento, así que en lugar de usar wp_enqueue_script , uso HEREDOC con la API Fetch para cargar todo de forma asincrónica en paralelo:

$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;

Y luego insértelos en la cabeza, a veces junto con estilos como este:

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

Resultando en una cascada como esta, cargando todo a la vez pero controlando el orden de ejecución:

Nota: Esto requiere el uso de Fetch API, que no está disponible en todos los navegadores.