Qual é a maneira preferida de adicionar arquivos javascript personalizados ao site?

Eu já adicionei meus scripts, mas queria saber o caminho preferido.
Acabei de colocar uma <script>tag diretamente no header.phpmeu modelo.

Existe um método preferido para inserir arquivos js externos ou personalizados?
Como vincular um arquivo js a uma única página? (Eu tenho a página inicial em mente)

Use wp_enqueue_script()no seu tema

A resposta básica é usar wp_enqueue_script()em um wp_enqueue_scriptsgancho para front-end admin_enqueue_scriptspara administrador. Pode parecer algo assim (que assume que você está chamando do functions.phparquivo do seu tema ; observe como faço referência ao diretório da folha 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" );
}

Esse é o básico.

Scripts dependentes predefinidos e múltiplos

Mas digamos que você deseja incluir o jQuery e o jQuery UI Sortable na lista de scripts padrão incluídos no WordPress e deseja que seu script dependa deles? Fácil, basta incluir os dois primeiros scripts usando os identificadores predefinidos definidos no WordPress e, para o seu script, fornecer um terceiro parâmetro ao wp_enqueue_script()qual é uma matriz dos identificadores de script usados ​​por cada script, da seguinte forma:

<?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 em um plug-in

E se você quiser fazer isso em um plug-in? Use a plugins_url()função para especificar o URL do seu arquivo 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 );
}

Versionando seus scripts

Observe também que, acima , demos um número de versão ao nosso plug-in e passamos como um quarto parâmetro para wp_enqueue_script(). O número da versão é gerado na fonte como argumento de consulta no URL para script e serve para forçar o navegador a baixar novamente o arquivo em cache, se a versão foi alterada.

Carregar scripts apenas nas páginas onde for necessário

A 1ª regra do Desempenho da Web diz Minimizar solicitações HTTP; portanto, sempre que possível, você deve limitar os scripts a carregar apenas quando necessário. Por exemplo, se você precisar apenas do seu script no administrador, limite-o às páginas de administrador usando o admin_enqueue_scriptsgancho:

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

Carregar seus scripts no rodapé

Se o seu script é um daqueles que precisam ser carregados no rodapé, existe um quinto parâmetro wp_enqueue_script()que diz ao WordPress para atrasá-lo e colocá-lo no rodapé (assumindo que o tema não tenha se comportado mal e que de fato chama o gancho wp_footer como todos bons temas para WordPress ):

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

Controle de granulação mais fina

Se você precisar de um controle mais refinado do que o Ozh, tenha um ótimo artigo intitulado Como: Carregar Javascript com o Plug-in do WordPress que detalha mais.

Desabilitando scripts para obter controle

Justin Tadlock tem um bom artigo intitulado Como desativar scripts e estilos , caso você queira:

1. Combine vários arquivos em arquivos únicos (a milhagem pode variar com o JavaScript aqui).
2. Carregue os arquivos apenas nas páginas em que estamos usando o script ou o estilo.
3. Pare de ter que usar! Important em nosso arquivo style.css para fazer ajustes simples de CSS.

Passando valores de PHP para JS com wp_localize_script()

Em seu blog, Vladimir Prelovac tem um ótimo artigo intitulado Práticas recomendadas para adicionar código JavaScript aos plug-ins do WordPress, onde ele discute o uso wp_localize_script()para permitir que você defina o valor das variáveis ​​no PHP do servidor para serem usadas posteriormente no Javascript do cliente.

Controle de grão realmente fino com wp_print_scripts()

E, finalmente, se você precisar de um controle realmente refinado, poderá analisar wp_print_scripts()como discutido no Beer Planet em uma postagem intitulada Como incluir CSS e JavaScript condicionalmente e somente quando necessário pelas postagens .

Epiloque

Para isso, é recomendável incluir os arquivos Javascript no WordPress. Se eu perdi alguma coisa (o que eu provavelmente tenho), informe-me nos comentários para que eu possa adicionar uma atualização para futuros viajantes.

Para complementar a maravilhosa ilustração do Mikes sobre o uso de enfileiramentos, gostaria de salientar que os scripts incluídos como dependências não precisam ser enfileirados ...

Usarei o exemplo sob os scripts em um cabeçalho de plug-in na resposta 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);
}

Isso pode ser aparado para ler ..

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

Quando você define dependências, o WordPress as encontra e as coloca prontas para o seu script, para que você não precise fazer chamadas independentes para esses scripts.

Além disso, alguns de vocês podem estar se perguntando se a configuração de várias dependências pode causar a saída de scripts na ordem errada, deixe-me dar um exemplo

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

Se o script dois dependesse do script três (ou seja, o script três deveria ser carregado primeiro), isso não importaria, o WordPress determinará as prioridades de enfileiramento para esses scripts e as exibirá na ordem correta, em suma, tudo será resolvido automaticamente. para você pelo WordPress.

Para pequenos pedaços de scripts, que talvez você não queira incluir em um arquivo separado, por exemplo, porque eles são gerados dinamicamente, o WordPress 4.5 e outras ofertas wp_add_inline_script. Essa função basicamente trava o script para outro script.

Digamos, por exemplo, que você esteja desenvolvendo um tema e que seu cliente possa inserir seus próprios scripts (como Google Analytics ou AddThis) na página de opções. Você pode então usar wp_add_inline_scriptpara travar esse script no seu arquivo js principal (digamos mainjs) assim:

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

Minha maneira preferida é obter um bom desempenho; portanto, em vez de usar, wp_enqueue_scripteu uso o HEREDOC com a API Fetch para carregar tudo de forma assíncrona em 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;

E insira-os na cabeça, às vezes junto com estilos como este:

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

Resultando em cascata que se parece com isso, carregando tudo de uma vez, mas controlando a ordem de execução:

Nota: Isso requer o uso da API de busca, que não está disponível em todos os navegadores.