uso de arquivos de estilos CSS e códigos JavaScript no WordPress são feitos em dois momentos distintos: inicialmente o desenvolvedor faz o registro dos arquivos que deseja utilizar e, dentro do tema ou plugin, posteriormente faz sua incorporação ao código HTML.

Funções de registro e inclusão de scripts (register e enqueue)

Para demonstrar esse comportamento será desenvolvido um plugin que insere no canto da tela um botão de voltar ao topo da página. O recurso possuirá apenas 3 arquivos: um .php para fazer a incorporação dos outros dois; sendo um .css para a formatação do botão e o outro .js para gerar a interação e o efeito esperado ao se clicar sobre o referido botão.

Dentro do arquivo .php serão utilizadas quatro funções do WordPress, duas para registro dos arquivos (wp_register_script e wp_register_style) e outras duas para incorporação (wp_enqueue_script e wp_enqueue_style).

<?php

// Plugin Name: JavaScript no WordPress - Ir ao topo

class WPJS_Totop
{

    public static function setup()
    {
        add_action( 'wp_enqueue_scripts', array( 'WPJS_Totop', 'register' ) );
        add_action( 'wp_enqueue_scripts', array( 'WPJS_Totop', 'enqueue' ) );
    }

    public static function register()
    {
        wp_register_script( 'wpjs-totop-js', plugin_dir_url( __FILE__ ) . 'wpjs-totop.js', array( 'jquery' ), null, true );
        wp_register_style( 'wpjs-totop-css', plugin_dir_url( __FILE__ ) . 'wpjs-totop.css', null, null, 'screen' );
    }

    public static function enqueue()
    {
        $types = array( 'post' );
        if ( is_singular( $types ) ) {
            wp_enqueue_script( 'wpjs-totop-js' );
            wp_enqueue_style( 'wpjs-totop-css' );
        }
    }

}

add_action( 'plugins_loaded', array( 'WPJS_Totop', 'setup' ) );

A separação permitiu criar a condição para inserir o recurso apenas quando um post for aberto. Caso o arquivo seja utilizado uma única vez e/ou exista o desejo de fazer a incorporação de modo direto sem o prévio registro; isso poderia ser feito utilizando a função de enqueue com os demais parâmetros preenchidos:

wp_enqueue_script( 'wpjs-totop-js', plugin_dir_url( __FILE__ ) . 'wpjs-totop.js', array( 'jquery' ), null, true ) );

As funções de script recebem como parâmetros o identificador único do arquivo, o endereço de sua localização, as dependências (quais outros scripts devem ser incorporados antes dele, no caso acima a jQuery), a versão do código e o valor boolean que define se o código será exibido no rodapé (true) ou não (false).

Já as rotinas de estilo, se diferem apenas no último parâmetro, onde ao invés de optar o local de exibição dos códigos, deve ser informado para qual mídia aquele arquivo .css se aplica (allscreenprint, etc).

Tanto arquivo .js como .css podem ser obtidos juntamente com o arquivo .php gratuitamente. Fazer download do plugin voltar ao topo.

Gerenciar códigos JavaScript em servidor local ou remoto

Como foi visto acima, o uso de arquivos JavaScript no WordPress é realizado mediante o uso de funções de registro (wp_register_script), incorporação (wp_enqueue_script) e também pode ser gerenciado com a função de remoção de registro (wp_deregister_script). Essa funcionalidade permite a manipulação tanto de arquivos locais como remotos.

Dependendo do script que se deseja incorporar ao Tema ou ao Plugin, o WordPress traz consigo uma série de recursos que podem ser utilizados sem que seja feito o registro prévio; pois isso já foi feito pelo próprio sistema.

wp_enqueue_script( 'quicktags' );

Alguns outros, mesmo que não exista entre os arquivos do sistema, também podem ser chamados da mesma forma pois o WordPress utiliza algum CDN para entregar o conteúdo.

wp_enqueue_script( 'prototype' );

Esse mesmo comportamento pode ser replicado nos arquivos de Plugins e Temas WordPress; pode ser incorporado algo que esteja dentro de suas estruturas de arquivos ou então em algum servidor remoto.

A inserção de um código que esteja dentro de um tema pode ser feita usando as funções get_template_directory_uri e get_stylesheet_directory_uri; ambas sem nenhum parâmetro. A primeira é usada para obter a URL completa, caminho absoluto, da pasta do Tema e a segunda traz o caminho da pasta onde o arquivo style.css está inserido; ou seja, traz a pasta do Tema Filho. Caso get_stylesheet_directory_uri seja usada em um Tema comum (que não seja filho de outro), o retorno será o mesmo que get_template_directory_uri.

No caso dos plugins, o caminho completo da pasta do plugin será dado por plugin_dir_url passando o arquivo que se deseja obter o caminho como parâmetro da função:

plugin_dir_url( __FILE__ );

Nesse caso será retornado o caminho onde o próprio arquivo está inserido.

Em situações onde se deseja fazer uso de códigos JavaScript de outros servidores, basta inserir a URL pretendida dentro da função de registro ou de incorporação direta.

// Tema
wp_register_script( 'theme-js', get_template_directory_uri() . 'theme.js', false, null, true );
// Tema Filho
wp_register_script( 'child-js', get_stylesheet_directory_uri() . 'child.js', false, null, true );
// Plugin
wp_register_script( 'plugin-js', plugin_dir_url( __FILE__ ) . 'plugin.js', false, null, true );
// Servidores remotos
wp_register_script( 'angular-js', 'https://ajax.googleapis.com/ajax/libs/angularjs/1.5.6/angular.min.js', false, null, true );

Essa questão de permitir tanto arquivos locais como remotos torna-se mais útil quando se faz necessário remover ou atualizar algum código que acompanha o WordPress, Tema ou Plugin em uso. Para remover algum script que tenha sido registrado com wp_register_script, a função que tira o registro e libera seu identificador (primeiro parâmetro) para um novo uso é a wp_deregister_script.

wp_deregister_script( 'jquery' );
wp_register_script( 'jquery', 'https://code.jquery.com/jquery-3.2.1.min.js', false, null, true );

Esse tipo de alteração requer algum cuidado pois alterar a versão de scripts ou simplesmente removê-los pode trazer problemas de compatibilidade e afetar o funcionamento de certos recursos.

JavaScript sempre no final do código HTML

Agora que você já sabe como incorporar os códigos JavaScript ao seu projeto, otimize essa incorporação inserindo seus códigos JS no final do código HTML, antes do fechamento da tag <body>. Essa otimização é feita, pois o carregamento desses arquivos, estando no rodapé de suas páginas, passa a ocorrer após a renderização do HTML (e muito provavelmente após o carregamento dos estilos CSS que são inseridos no cabeçalho <head>).

Com isso até que o código seja carregado, o usuário não precisa ser impactado por uma tela em branco ou um site que demora a carregar as primeiras informações.

No WordPress, quando é preciso incorporar algum código JavaScript ao Tema é feito uso da função wp_enqueue_script.

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

Repare que o último parâmetro permite inserir o script em questão no rodapé, bastando informar o valor true para ele.

No entanto, não basta que você insira somente os seus arquivos JS para o rodapé, se você pretende usar dessa boa prática você precisa também informar ao WordPress para que ele carregue os seus scripts da mesma forma.

add_action( 'init', 'scripts_in_footer' );

function scripts_in_footer()
{
    remove_action( 'wp_head', 'wp_print_scripts' );
    remove_action( 'wp_head', 'wp_print_head_scripts', 9 );
    remove_action( 'wp_head', 'wp_enqueue_scripts', 1 );

    remove_action( 'embed_head', 'enqueue_embed_scripts', 1 );
    remove_action( 'embed_head', 'wp_print_head_scripts', 20 );

    add_action( 'wp_footer', 'wp_print_scripts' );
    add_action( 'wp_footer', 'wp_enqueue_scripts' );
    add_action( 'wp_footer', 'wp_print_head_scripts' );

    add_action( 'embed_footer', 'enqueue_embed_scripts' );
    add_action( 'embed_footer', 'wp_print_head_scripts' );
}

Feito isso os códigos que antes eram inseridos no cabeçalho vão para o rodapé do site. Aliado a essa técnica você pode também querer remover outros códigos de JavaScript que o WordPress insere no cabeçalho do seu Tema.

Remova os Emojis do seu WordPress

Além de incorporar os códigos próprios e do sistema no rodapé de seus arquivos, você talvez queira remover instruções JavaScript indesejadas para o seu projeto; como é o caso dos Emojis.

O WordPress permite por padrão que os usuários utilizem Emojis dentro dos seus Temas. Diferente dos Smileys que são apenas as representações de emoções em escrita – no WP são representados graficamente 😀 – os Emojis são tratados de forma diferente e permitem inserir uma maior variação de imagens nas publicações. 🏆

No entanto caso você não faça uso desse recurso, ainda assim o WordPress acaba por carregar uma série de códigos no cabeçalho do HTML do seu Tema referente ao uso de Emojis.

 

Códigos JavaScript dos Emojis do WordPress

Para remover esses códigos utilize:

function disable_emoji()
{
    remove_action( 'wp_head', 'print_emoji_detection_script', 7 );
    remove_action( 'wp_print_styles', 'print_emoji_styles' );
}
add_action( 'init', 'disable_emoji' );

Agora caso você queira remover o recurso não apenas na parte pública do site, mas em todos os lugares onde ele é inserido, será preciso remover mais algumas ações:

function disable_emoji()
{
    // ... continuação
    remove_action( 'admin_print_scripts', 'print_emoji_detection_script' );
    remove_action( 'admin_print_styles', 'print_emoji_styles' );

    remove_filter( 'wp_mail', 'wp_staticize_emoji_for_email' );

    remove_filter( 'the_content_feed', 'wp_staticize_emoji' );
    remove_filter( 'comment_text_rss', 'wp_staticize_emoji' );
}

Thickbox. Usando as janelas modais do WordPress

Se por um lado você pode remover arquivos JS do WordPress que não utiliza, por outro você também pode incorporar recursos do core do sistema em seus Temas e Plugins; como por exemplo o Thickbox.

Thickbox é o recurso responsável por exibir as janelas de conteúdo, modais, caixas de diálogo, popups que o WordPress possui. Esse recurso pode ser facilmente utilizado também na área pública do site bastando ao desenvolvedor incorporar os arquivos do Thickbox e respeitar a estrutura dos códigos HTML necessária ao funcionamento do recurso.

A inserção dos arquivo .js e .css pode ocorrer de duas formas diferentes. A primeira é através das funções de incorporação de estilos e scripts:

wp_enqueue_style( 'thickbox' );
wp_enqueue_script( 'thickbox' );

A outra forma é simplesmente disparar a função add_thickbox onde se deseja incorporar o recurso.

add_thickbox();

Pronto! O Thickbox já pode ser utilizado. Após incorporar seus códigos, a exibição de conteúdo dentro do modal ocorre em links que estão marcados com a classe thickbox.

<a class="thickbox" href="http://seusite.com.br/wp-content/uploads/2018/07/31/imagem.jpg">Exibir imagem dentro do Thickbox</a>

Essa funcionalidade usada pelo WordPress permite exibir itens em formato de galeria, onde é possível utilizar a navegação para ir de um arquivo a outro que esteja com o Thickbox aplicado. Esse recurso de galeria requer a inserção do atributo rel na tag HTML do link.

<a class="thickbox" rel="custom" href="http://seusite.com.br/wp-content/uploads/2018/07/31/imagem-1.jpg" title="Imagem #1">Exibir Imagem #1</a>
<a class="thickbox" rel="custom" href="http://seusite.com.br/wp-content/uploads/2018/07/31/imagem-2.jpg" title="Imagem #2">Exibir Imagem #2</a>
<a class="thickbox" rel="custom" href="http://seusite.com.br/wp-content/uploads/2018/07/31/imagem-3.jpg" title="Imagem #3">Exibir Imagem #3</a>

Imagens externas ao site também são aceitas, basta encaminhar o endereço completo da imagem; um link direto mesmo. Informando o atributo title para o link, esse conteúdo passa a ser apresentado como título do modal.

<a class="thickbox" title="Logo do WordPress" href="https://s.w.org/about/images/logos/wordpress-logo-stacked-rgb.png">Exibir logo do WordPress</a>

Outros dois formatos são possíveis de serem exibidos dentro da caixa de diálogo do Thickbox no WordPress; o iframe e conteúdos internos da página. A exibição de um iframe requer o link para o atributo src do iframe seguida da instrução TB_iframe=true. Em adição a esse parâmetro, as dimensões de largura e altura precisam ser informadas da seguinte maneira:

<a class="thickbox" title="WordPress 4.7" href="https://www.youtube.com/embed/KiS8rZBeIO0?TB_iframe=true&width=560&height=315">WordPress 4.7</a>

O conteúdo interno da página segue o mesmo padrão. O link deve informar na propriedade href a instrução #TB_inline seguida do parâmetro inlineId que deve receber o id do conteúdo que será inserido dentro da janela. Requer a inserção das dimensões assim como para o uso do iframe.

Thickbox sendo usado na área pública de um Tema WordPress

<div style="display: none;" id="meu-modal"><p>Conteúdo interno</p></div>
<a class="thickbox" href="#TB_inline?inlineId=meu-modal&width=480&height=90" title="Título">Conteúdo da div oculta</a>

Galeria do WordPress em formato de Carrossel (Gallery Carousel)

Assim como você fez uso dos códigos que estão no core do WordPress, você pode também utilizar bibliotecas, APIs e instruções de terceiros. Veja esse funcionamento na prática ao incorporar um carrossel a galeria de imagens padrão do WordPress.

Com a própria Galeria de Imagens do WordPress, a que pode ser criada e inserida pelo editor visual dos posts, e algumas instruções de JavaScript é possível personalizar a exibição das imagens transformando a galeria em um Carrossel. Poucas linhas de CSS ajudam a formatar e adequar o carrossel da galeria a identidade visual do Tema em uso.

Galeria do WordPress no editor visual

Esse recurso será obtido ao gerar uma galeria de imagens padrão do WordPress com o projeto Slick. Trata-se de um plugin jQuery com suporte a múltiplas resoluções, transições CSS, eventos de touch e swipe e uma série de outros recursos.

A implantação desse recurso fará uso de 3 arquivos presentes no plugin:

  • slick.min.js: o plugin jQuery do carousel em si;
  • slick.min.css: as formatações essenciais a seu funcionamento;
  • slick-theme.min.css: exibição personalizada dos elementos do carrossel (opcional).

Além desses serão utilizados mais um arquivo .js para fazer a chamada do plugin e um outro .css para ajustar a exibição dos elementos do carousel ao Tema.

Criada a galeria, a inserção do shortcode dentro do conteúdo de uma publicação vai gerar um código HTML similar a:

<div id="gallery-1" class="gallery gallery-columns-3">
    <figure class="gallery-item"></figure>
    <!-- // e o mesmo para os demais itens

Seguindo a estrutura que o plugin Slick precisa para funcionar, basta fazer a chamada do mesmo utilizando a classe da camada que abriga todas as imagens da galeria.

$( ".gallery" ).slick({
    infinite: true,
    slidesToShow: 3,
    slidesToScroll: 3
});

Porém antes de incorporar os arquivos ao Tema é preciso ter em mente que tais arquivos somente serão úteis ao projeto quando uma publicação estiver aberta e também, quando existir uma galeria em seu conteúdo. Por isso, ao invés de usar o gancho padrão para incorporar scripts wp_enqueue_scripts, será feita uma verificação do conteúdo usando o filtro the_content.

add_action( 'the_content', array( 'WPJS_Carousel', 'enqueue' ) );
public static function enqueue( $c )
{
     if ( has_shortcode( $c, 'gallery' ) ) {
         // incorpora os scripts ao Tema
     }
     return $c;
}

O uso da função has_shortcode verifica o conteúdo a procura do shortcode, parâmetros da função. O filtro precisa retornar o conteúdo para que este seja exibido corretamente.

Inserido os códigos .js e .css no tema Twenty Fifteen, o resultado será este:

Galeria do WordPress com carrossel aplicado

Uma boa estratégia é fazer uso dessa formatação da galeria do WordPress em carrossel juntamente com um outro plugin jquery (talvez o próprio Thickbox, visto acima) a fim de manter o visitante dentro do site, do post mesmo quando ele clica sobre uma imagem (cujo link destino seja o Arquivo de Mídia).

Download do plugin WordPress Gallery Shortcode Carousel

JavaScript próprio com a Criação de um Preloader para o conteúdo

Como você pôde ver até aqui, o uso de JavaScript no WordPress pode ser feito com códigos do sistema, de terceiros ou instruções próprias. Um Tema que segue a otimização de incorporar arquivos .css e .js apenas no rodapé do HTML precisa lidar com um problema de apresentação delicado. Dependendo da conexão do visitante, é possível que ele veja o site sem formatação, com problemas aparentes no layout.

Em casos como esse uma técnica interessante de ser adotada é apresentar ao visitante uma informação de espera enquanto ele aguarda o carregamento da página.

Essa informação que antecede o conteúdo é denominada preloader. Com o JavaScript é possível realizar alguns processos no pré-carregamento da página, enquanto ela é carregada; e também logo após, concluído o carregamento.

Desse modo a criação de um preloader no WordPress será feita respeitando o seguinte processo:

  • logo após a tag <body> será inserido os códigos do preloader;
  • o preloader irá aguardar a página ser construída exibindo um GIF de loading (carregando);
  • concluído o carregamento serão removidos do HTML os arquivos e informações do preloader.

O uso do preloader requer uma pequena intervenção no código do seu Tema. Logo após a abertura da tag <body>, insira a seguinte instrução:

<?php do_action( 'wpjs_preloader' ); ?>

Feito isso, os processos de dentro do plugin serão poucos. Ele apenas irá inserir uma camada ao HTML para sobrepor o conteúdo da página enquanto ela é carregada:

class WPJS_Preloader
{

    private static $url;

    public static function setup()
    {
        self::$url = plugin_dir_url( __FILE__ );

        add_action( 'wpjs_preloader', array( 'WPJS_Preloader', 'enqueue' ) );
    }

    public static function enqueue( $c )
    {
        ?>
        <div id="preloader">
            <link type="text/css" rel="stylesheet" href="<?php echo self::$url; ?>wpjs-preloader.css">
            <script type="text/javascript" src="<?php echo self::$url; ?>wpjs-preloader.js"></script>
        </div>
        <?php
    }

}

add_action( 'plugins_loaded', array( 'WPJS_Preloader', 'setup' ) );

A incorporação tanto de CSS como de JS é feita de modo direto, pois o código JavaScript puro (não está sendo usada a jQuery) irá remover a div em questão logo após a página ter sido devidamente carregada.

Note que dentro dessa camada (#preloader) você pode inserir qualquer informação HTML que deseja apresentar como mensagem de espera. Entretanto tome cuidado para não incluir informação demais, senão até mesmo o preloader poderá demorar a aparecer.

Download do plugin Preloader no WordPress

Como usar variáveis do WordPress em códigos JavaScript

Em algum momento no desenvolvimento dos seus recursos para WordPress você precisará compartilhar informações da base de dados com o JavaScript. O uso de códigos JS para inserir imagens do seu Tema ou Plugin, fazer requisições AJAX ou quaisquer outros processos que precisem de variáveis do servidor, que estão armazenadas pelo WordPress; é um processo de integração facilmente resolvido com a função wp_localize_script.

Por padrão os registros e uso dos scripts no WordPress são feitos com wp_register_script e wp_enqueue_script. Uma vez incorporado o script ao site, utilize a função wp_localize_script para incorporar sua variável ao JS.

add_action( 'wp_enqueue_scripts', 'custom_scripts' );

function custom_scripts()
{
    wp_enqueue_script( 'meu-script' );
    wp_localize_script(
        'meu-script',
        'ajax_url',
        admin_url( 'admin-ajax.php' )
    );
}

Caso precise transferir mais de um valor, ao invés de invocar a mesma função várias vezes, você pode usar o último parâmetro como um Array.

wp_localize_script(
    'meu-script',
    'wp_vars',
    array(
        'wp_url'   => get_bloginfo( 'wpurl' )
        'home_url' => get_bloginfo( 'url' )
    )
);

Desse modo o trabalho com as variáveis no JavaScript será dado através de um objeto.

alert( wp_vars.wp_url );

Requisições AJAX no WordPress

Trabalhar com requisições AJAX no WordPress requer o uso de alguns procedimentos básicos. O processo para esse tipo de requisição deve ser seguido, pois com ele é possível carregar o WordPress e definir as instruções a serem processadas de dentro de um Tema ou Plugin.

Para exemplificar o processo foi criado um plugin que insere ao final do conteúdo dos posts um link para exibir o email do administrador do site (editável em ConfiguraçõesGeral > Endereço de email). Apenas um exemplo que pode ser expandido ou adptado para buscar e exibir qualquer informação que seja gerenciada pelo WordPress.

AJAX através dos Ganchos (ações)

Uma requisição AJAX direcionada ao endereço do site ou diretamente a um arquivo do Tema ou de algum plugin não traria o efeito desejado ao desenvolvedor. No primeiro caso seriam executadas todas as rotinas de front-end e sem o devido tratamento o retorno seria o próprio HTML do Tema, sem muitas possibilidades. Já em requisições direcionadas a um arquivo específico, as rotinas do WordPress não seriam carregadas e assim não poderiam ser utilizadas por esse arquivo.

Por tais razões o WordPress disponibiliza um arquivo onde as requisições devem ser direcionadas. Esse arquivo é o wp-admin/admin-ajax.php. Apontando a requisição para esse endereço é preciso enviar em meio aos dados (pode ser via $_GET ou via $_POST, independente) a variável action.

O valor da variável action vai determinar a criação dos ganchos a serem usados dentro do Tema ou dos Plugins:

  • wp_ajax_[action]: para requisições privadas, onde o usuário está logado;
  • wp_ajax_nopriv_[action]: para requisições públicas, não logado.

Um pouco de código auxiliará o entendimento desse processo. A começar pela criação do plugin:

// Plugin Name: JavaScript no WordPress - Ajax
class WPJS_Ajax
{
    public static function setup()
    {
        add_action( 'wp_enqueue_scripts', array( 'WPJS_Ajax', 'ajax' ) );
    }

    public static function ajax()
    {
        wp_enqueue_script( 'wpjs-ajax-js', plugin_dir_url( __FILE__ ) . 'wpjs-ajax.js', array( 'jquery' ), null, true );
        wp_localize_script(
            'wpjs-ajax-js',
            'wp_obj',
            array(
                'ajax_url' => admin_url( 'admin-ajax.php' )
            )
        );
    }
}
add_action( 'plugins_loaded', array( 'WPJS_Ajax', 'setup' ) );

O registro do arquivo JS está sendo feito no mesmo momento em que é incorporado à página. Em seguida a função wp_localize_script é responsável por fazer a comunicação, transmitir variáveis do WordPress para o escopo do JavaScript. A função recebe o identificador do código ao qual está submetida, seguida de um objeto que será usado no arquivo .js e por fim um array com as propriedades desse objeto.

Do lado JavaScript para acessar esses valores basta referenciar o nome do objeto e o nome da propriedade. Com isso o código JS para a requisição ficará do seguinte modo:

$.ajax({
    url: wp_obj.ajax_url,
    type: 'post',
    data: {
        action: 'get_admin_email'
    },
    dataType: 'html',
    success: function ( r ) {
    }
});

Retomando o funcionamento do uso de AJAX no WordPress, devem ser criados os ganchos para receber os dados e processar a requisição no arquivo PHP. Dentro do método setup:

add_action( 'wp_ajax_get_admin_email', array( 'WPJS_Ajax', 'ajax_action' ) );
add_action( 'wp_ajax_nopriv_get_admin_email', array( 'WPJS_Ajax', 'ajax_action' ) );

O mesmo valor passado através da variável action está representado em wp_ajax_ e wp_ajax_nopriv_. Com isso, tanto usuários logados como deslogados, terão acesso ao recurso. E o método ajax_action, da classe do plugin, é o que será executado quando a requisição acontecer.

public static function ajax_action()
{
    printf(
        '<a href="mailto:%1$s" title="Fale com o administrador">%1$s</a>',
        get_option( 'admin_email' )
    );
    wp_die();
}

As informações do método devem ser exibidas em tela pelo PHP (echoprintprintf, etc). Ao final dos processos o script deve ser interrompido para que não apareça a string ‘0’ usada pelo WordPress como retorno caso a action não tenha sido encontrada ou executada devidamente.

Utiliza-se preferencialmente a função wp_die para que sejam disparadas as rotinas atribuídas ao filtro wp_die_ajax_handler. Caso isso não seja relevante a requisição, as instruções podem terminar com o uso de exit ou die do PHP.

Download da classe exemplo de requisições AJAX no WordPress