Criando um site com o poder do WordPress: Introdução e Configuração

() translation by (you can also view the original English article)

Na série de introdução a REST API do WordPress, aprendemos a utilizar as funcionalidades básicas oferecidas pela API e a flexibilidade que ela oferece para criar aplicações com o back end do WordPress. Olhamos para os recursos, rotas e métodos suportados em operações CRUD.

Nesta série sobre criar sites (front end) com o poder do WordPress utilizando a Rest API e AngularJS, vamos colocar o conhecimento adquirido na série anterior em prática. Vamos aprender como podemos utilizar este conhecimento para modificar o tema padrão suportado pelo WordPress até agora. Vamos planejar e criar uma aplicação single-page (que nomeei de Quiescent) com o back end do WordPress utilizando posts, usuários e categorias. Vamos configurar as rotas do AngularJS e criar diretivas e controladores para os recursos mencionados.

Na primeira parte da séria, nós vamos:

avaliar os requerimentos para criar um layout com ajuda de wireframes
baixar e instalar o pacote HTML para começar a trabalhar
criar um plugin para o WordPress baseado nessa avaliação

Então, vamos começar avaliando os requerimentos para criação do front end.

Planejando as Tarefas

A parte inicial de qualquer projeto deve ser avaliar os requerimentos do projeto e fazer o planejamento de acordo. Isso deixa o projeto mais conciso e nos ajuda a pensar claramente em termos de funcionalidades e recursos da aplicação.

Como mencionado anteriormente, precisamos de listing pages e single pages para o três recursos:

Posts
Categorias
Usuários

Vamos primeiro criar o template para recurso Posts. Vamos precisar de dois templates para este recurso, um template listing e outro single post. O template listing vai apresentar posts com paginação e links para ir de uma categoria de posts para outra. O template single post vai apresentar apenas o post.

Abaixo está o wireframe da página de listagem de artigos:

E o seguinte é o wireframe para o único modelo de artigo:

Como podemos ver nos wireframes acima, os requisitos são bem simples, assim como qualquer modelo de blog padrão. Mas quando comparamos os wireframes acima com a resposta padrão que a API WP REST fornece para artigos, nos deparamos com a conclusão de que os seguintes itens estão faltando no objeto de resposta padrão:

link de imagem em destaque
nome do autor
nomes de categorias e links

Por isso, precisamos modificar a resposta do recurso Posts para incluir esses itens. Faremos isso mais adiante neste tutorial, criando um complemento complementar para o WordPress.

Vamos analisar agora os requisitos para os recursos de categorias e usuários, observando os dois wireframes a seguir.

Abaixo está o wireframe para o modelo de categoria:

E aqui está o wireframe para o modelo do usuário:

Observando os dois wireframes acima, fica claro que eles não exigem o registro de campos adicionais em suas respostas padrão. Mas, se olharmos atentamente para a página de perfil do autor, precisamos adicionar um tamanho de gravatar adicional para considerar o tamanho da imagem em nosso HTML. Essa funcionalidade também pode ser obtida no plug-in complementar.

Um dos princípios fundamentais e mais defendidos da engenharia de software é o princípio DRY (Don't Repeat Yourself). Ao analisar os modelos acima, vemos que a listagem de artigos está sendo repetida em quase todos os modelos de listagem de uma forma ou de outra. Então, vamos seguir em frente e criar uma diretiva AngularJS comum para as listas que serão usadas em todos os modelos acima, e essa diretiva incluirá a funcionalidade, incluindo a publicação de paginação e a recuperação de um subconjunto de artigos para determinados parâmetros.

Agora que avaliamos os requisitos gerais para a criação do aplicativo, podemos nos aprofundar na parte de codificação a partir da próxima seção.

Requisitos do tutorial

Antes de começarmos a trabalhar para construir o aplicativo, você precisa ter certos aplicativos instalados em seu sistema. Estas aplicações são:

uma instalação do WordPress com o plugin WP REST API ativado e alguns dados de demonstração
Git para clonar o repositório HTML (não é necessário, no entanto, já que você também pode baixar o repositório diretamente do site do GitHub através da GUI)
Node.js para trabalhar com comandos npm e gulp
GulpJS para executar tarefas de minificação e otimização no pacote HTML

Se você tem vindo a desenvolver para a web por um tempo, há uma boa chance de que você já tenha essas coisas instaladas em seu sistema. Caso contrário, recomendo que você dê uma olhada nos sites e na documentação oficiais deles para configurá-los.

Download e instalação do pacote HTML

Para tornar as coisas mais fáceis de serem seguidas, já criei modelos HTML básicos para os wireframes analisados acima.

Primeiro de tudo, você precisa clonar o repositório de pacotes HTML do GitHub:

1	$ git clone https://github.com/bilalvirgo10/quiescent-rest-api-html.git

Depois de clonar o repositório, você precisa navegar no diretório usando o seguinte comando:

1	$ cd path/to/cloned/repository

Não importa se você está usando o OS X, Windows ou Linux, porque o comando cd acima funcionará em quase todos os sistemas operacionais.

Agora você precisa instalar os módulos Node.js usando:

1	$ npm install

O comando acima levará algum tempo para ser concluído, dependendo da velocidade de sua conexão à Internet.

Tendo instalado os módulos necessários, você pode finalmente compilar a fonte usando o comando gulp:

$ gulp

Isso produz uma nova pasta chamada dist que contém a fonte compilada para HTML e seus ativos.

O comando npm install que executamos acima também instala um módulo Node.js chamado http-server que fornece uma maneira rápida e fácil de configurar um servidor HTTP básico dentro de qualquer diretório. Você pode verificar a origem compilada, navegando no diretório dist e executando o seguinte comando:

1	$ http-server

Isto irá ecoar alguns endereços na tela para o servidor que você pode inserir no seu navegador para começar a visualizar o HTML.

$ http-server
Starting up http-server, serving ./
Available on:
    https:192.168.0.104:8080
    http:192.168.56.1:8080
    http:127.0.0.1:8080
Hit CTRL-C to stop the server

Isso é tudo sobre baixar e compilar o pacote HTML básico que funcionará como backbone para nosso desenvolvimento futuro.

Construindo o plugin Quiescent Companion

Tendo baixado e instalado os módulos necessários para o pacote HTML, agora estamos prontos para construir a funcionalidade do lado do servidor para suportar o front-end.

Em uma seção anterior, analisamos os requisitos para a construção do front end com a API WP REST e o AngularJS. Vamos dar uma olhada novamente nos itens necessários que precisamos para criar o front end:

Imagem em destaque para o artigo. Também precisamos registrar um novo tamanho de imagem no WordPress para considerar o tamanho da imagem em nosso HTML.
Nome do autor do artigo. Isso pode ser recuperado usando o ID do autor que está disponível no objeto de resposta padrão.
Lista de categorias associadas à artigos. Isso pode ser conseguido usando o ID do artigo.
Um novo tamanho de imagem para o gravatar para contabilizar o tamanho da imagem do perfil do autor em nosso HTML.

Portanto, precisamos de três campos adicionais para o recurso Posts e também precisamos adicionar novos tamanhos de imagem para a imagem em destaque e o gravatar do usuário.

Vamos começar criando um novo diretório para o nosso plugin na pasta / wp-content / plugins e nomeando-o quiescent-companion. Dentro desse diretório, crie um novo arquivo PHP chamado quiescent-companion.php e cole o seguinte código para a definição do plugin:

<?php
/**
 * Plugin Name: Quiescent Companion
 * Description: Plugin to work with the Quiescent WP REST API theme
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 */

Se você acompanha comigo desde a minha série introdutória sobre a API REST do WP, já aprendeu a modificar a resposta do servidor para um recurso específico usando o método register_rest_field (). Se você não deu uma olhada nisso, recomendo que faça isso consultando o artigo sobre como modificar as respostas do servidor.

O método register_rest_field () aceita três argumentos para o nome do recurso a ser modificado, o nome do campo e uma matriz de argumentos para o campo. Essa matriz de argumentos contém o retorno de chamada de recuperação, o retorno de chamada de atualização e o esquema do campo.

Aqui está o código para adicionar um campo personalizado para a imagem em destaque do artigo:

<?php
/**
 * Modifying the response for the Post object
 */
function quiescent_modify_post_response() {
    // adding a field for the featured image
    register_rest_field( 'post', 'quiescent_featured_image', array(
        'get_callback'  	=> 'quiescent_get_featured_image',
        'update_callback'	=> null,
        'schema'                => null
    ) );
}
add_action( 'rest_api_init', 'quiescent_modify_post_response' );

O método register_rest_field () é chamado com a ação rest_api_init.

É sempre uma boa prática prefixar o nome do campo personalizado para que ele não entre em conflito com nenhum outro campo no futuro. Por isso nomeamos nosso campo personalizado quiescent_featured_image. O método responsável por recuperar essa imagem em destaque é quiescent_get_featured_image e a definimos da seguinte forma:

<?php
/**
 * Function to retrieve featured image link
 */
function quiescent_get_featured_image( $post, $field_name, $request ) {
    $attachment_id = $post['featured_media'];
    $attachment_info = wp_get_attachment_image_src( $attachment_id, 'quiescent_post_thumbnail' );
    return $attachment_info[0];
}

Esse método recebe três argumentos para a matriz do artigo, o nome do campo e o objeto da requisição. A matriz de artigos contém informações necessárias sobre o artigo atual, incluindo seu ID, título, conteúdo etc. Ao usar essas informações, podemos recuperar qualquer informação arbitrária associada ao artigo. Portanto, usamos o ID de mídia com artigo para recuperar o link da imagem em destaque do artigo usando o método wp_get_attachment_image_src ().

Além do código acima para registrar o campo personalizado para o link da imagem em destaque do artigo, também precisamos registrar um tamanho de imagem personalizado de acordo:

<?php
/**
 * Adding image size for the featured image
 */
function quiescent_add_image_size() {
    add_image_size( 'quiescent_post_thumbnail', 712, 348, true );
}
add_action( 'init', 'quiescent_add_image_size' );

O código acima usa o método add_image_size () para registrar um novo tamanho de imagem de 712 px por 348 px, e usamos quiescent_post_thumbnail como o nome do novo tamanho da imagem.

Salve o código e certifique-se de que o plugin Quiescent Companion esteja ativado no seu administrador do WP. Envie uma solicitação de teste para a rota / wp / v2 / posts e o servidor retornará o link da imagem em destaque no campo quiescent_featured_image no objeto de resposta:

...
"tags": [],
"quiescent_featured_image": "http://localhost/wordpress/wp-content/uploads/2016/02/hot-chocolate-1058197_1920-712x348.jpg",
"_links": {
...

Agora que adicionamos com sucesso o link da imagem em destaque na resposta, os outros dois campos restantes a serem adicionados são para o nome do autor e a lista de nomes de categorias.

Para adicionar o nome de exibição do autor do artigo, modificamos a função quiescent_modify_post_response () para incluir outra chamada ao método register_rest_field () da seguinte forma:

<?php
// adding a field for author name
register_rest_field( 'post', 'quiescent_author_name', array(
    'get_callback'      => 'quiescent_get_author_name',
    'update_callback'   => null,
    'schema'            => null
) );

Chamamos esse campo personalizado de quiescent_author_name e a função de retorno de chamada para recuperar o valor desse campo é a seguinte:

<?php
/**
 * Function to retrieve author name
 */
function quiescent_get_author_name( $post, $field_name, $request ) {
    return get_the_author_meta( 'display_name', $post['author'] );
}

Aqui, usamos o método get_the_author_meta () para recuperar o nome de exibição do autor do artigo.

Para o último campo para nomes de categoria, a chamada para o método register_rest_field () é a seguinte:

<?php
// adding a field for categories
register_rest_field( 'post', 'quiescent_categories', array(
    'get_callback'      => 'quiescent_get_categories',
    'update_callback'   => null,
    'schema'            => null
) );

A chamada acima deve ir dentro da função quiescent_modify_post_response (). O método de retorno de chamada quiescent_get_categories () é:

<?php
/**
 * Function to retrieve categories
 */
function quiescent_get_categories( $post, $field_name, $request ) {
    return get_the_category( $post['id'] );
}

O código acima usa o método get_the_category () para recuperar as categorias do artigo atual. Esse método retorna uma matriz de objetos, com cada objeto representando uma categoria que pertence ao artigo atual.

Agora que escrevemos todo o código acima, três novos campos agora são adicionados ao objeto de resposta padrão para o recurso de Posts. Esses três novos campos são:

quiescent_featured_image
quiescent_author_name
quiescent_categories

Por padrão, a resposta padrão do recurso Users contém URLs de avatar para tamanhos de 24 px, 48 px e 96 px. A última coisa que precisamos fazer agora é adicionar um URL para um tamanho de gravatar adicional de 207 px para o recurso Users. Então crie uma nova função chamada quiescent_modify_user_response () e conecte-a à ação rest_api_init:

<?php
/**
 * Modifying the response for the User object
 */
function quiescent_modify_user_response() {
    
}
add_action( 'rest_api_init', 'quiescent_modify_user_response' );

Dentro desta função, adicionamos uma chamada ao método register_rest_field () para adicionar um campo chamado quiescent_avatar_url para o objeto de user:

<?php
/**
 * Modifying the response for the User object
 */
function quiescent_modify_user_response() {
    // adding a field for 207 X 207 avatar
    register_rest_field( 'user', 'quiescent_avatar_url', array(
        'get_callback'      => 'quiescent_get_user_avatar',
        'update_callback'   => null,
        'schema'            => null
    ) );
}

O método de retorno de chamada quiescent_get_user_avatar () é o seguinte:

<?php
/**
 * Retrieving the avatar for the user
 */
function quiescent_get_user_avatar( $user, $field_name, $request ) {
    $args = array(
        'size'  => 207
    );
    
    return get_avatar_url( $user['id'], $args );
}

Esse método usa o método get_avatar_url () para retornar a URL de um gravatar de tamanho 207 px por 207 px.

Envie uma solicitação GET para a rota / wp / v2 / users e o servidor retornará um campo adicional denominado quiescent_avatar_url juntamente com o objeto de resposta padrão:

1	...
2	"quiescent_avatar_url": "http://0.gravatar.com/avatar/?s=207&d=mm&r=g",
3	...

Isso é tudo sobre a construção do plugin complementar. O código fonte completo pode ser obtido do repositório Envato Tuts + GitHub.

Agora que o plug-in foi concluído, agora estamos prontos para começar a trabalhar com o AngularJS para criar modelos, rotas e serviços para recursos, o que faremos na próxima parte da série.

O que vem a seguir?

Neste tutorial, criamos uma base para a criação de um front end com tecnologia WordPress usando a API WP REST e o AngularJS. Analisamos os requisitos do projeto com wireframes e criamos um complemento complementar para o backend.

Na próxima parte da série, começaremos a trabalhar com o pacote HTML que baixamos anteriormente neste tutorial. Vamos inicializar o aplicativo AngularJS, configurar o roteamento e criar serviços RESTful para recursos de Posts, Users e Categories, portanto, fique atento ...