Tutorial: Criar um Slider como um Bloco Gutenberg Dinâmico

Este tutorial mostrará como criar um bloco dinâmico do WordPress Gutenberg. O resultado final é um controle deslizante que mostra a imagem em destaque das postagens da categoria selecionada. O código inclui o uso de um componente de ordem superior (withSelect) para buscar todas as categorias no editor de blocos.

O que vamos fazer

O bloco renderizará um slider simples usando o script jQuery Cycle2. Mas você pode usar qualquer outro script de controle deslizante. O bloco irá dentro do editor renderizar uma lista de todas as categorias permitindo ao usuário selecionar uma categoria. Ao exibir o bloco no frontend, ele buscará dinamicamente as postagens da categoria escolhida e mostrará suas imagens em destaque como slides. Este tutorial irá mantê-lo bastante simples, permitindo que você expanda e ajuste seu controle deslizante como quiser.

Optei por não renderizar a apresentação de slides dentro do editor. Normalmente, você garante que a renderização no editor e no frontend seja a mesma. Mas no caso de um slider eu gosto de simplificar para não explodir o usuário com animações constantes dentro do editor.

O bloco terá apenas duas configurações; a escolha da categoria e o número de slides (posts). Eu recomendo adicionar mais configurações, como velocidade do slide, configurações para exibir pílulas, setas, texto e outras configurações típicas do controle deslizante. Deve ser bem simples adicionar essas configurações você mesmo.

Todo o código é escrito em Javascript ES6 / ES2015+. Tenha em mente que este código precisa do Babel para transformar e construir os arquivos Javascript finais. Confira o guia abaixo se você não sabe como.

Configure os arquivos

Neste exemplo estamos criando o bloco dentro de um tema. Na pasta do tema tenho uma subpasta ‘ gutenberg/‘ onde coloquei meu arquivo package.jsone webpack-config.js. Dentro da subpasta ‘ src/‘ nesta pasta é onde coloco todos os meus arquivos de compilação. Minha configuração do webpack está configurada para colocar os arquivos de compilação na subpasta do meu tema ‘ assets/js/‘.

Crie um novo arquivo de origem vazio theme-folder/gutenberg/src/block-slider.jse configure o Webpack para criar o arquivo de compilação em theme-folder/assets/js/block-slider.js. Você pode alterar os locais e/ou nomes de arquivos como quiser, apenas lembre-se de ajustar o código abaixo.

Também precisamos baixar o script de controle deslizante necessário. Você pode baixar o Cycle2 neste link ou pode usar qualquer outro script de slide e ajustar o código abaixo. Estou colocando o jquery.cycle2.min.jsarquivo na pasta da pasta do meu tema /assets/js/.

Também vou preparar um pequeno arquivo CSS que será carregado apenas no editor. Nós apenas um pequeno pedaço de estilo para tornar a categoria ideal. Eu crio um arquivo vazio editor-block-slider.csse coloco em theme-folder/assets/css/.

Finalmente vamos para um arquivo PHP que é carregado no tema. Para simplificar, estou fazendo a parte do PHP no arquivo functions.php.

Registre o bloco Gutenberg em PHP

Todos os blocos Gutenberg devem ser registrados com [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Eu prefiro chamá-lo dentro de uma função ligada a init. O primeiro parâmetro é o nome do seu bloco, incluindo o namespace. Eu decidi chamar meu script de controle deslizante awp/slider(ajuste como quiser). O segundo argumento é uma matriz de argumentos.

Dentro da mesma função, registrarei o script de construção [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)()e registrarei meu arquivo CSS do editor com [wp_register_style](https://developer.wordpress.org/reference/functions/wp_register_style/)(). Ambos os identificadores serão adicionados como argumentos para ‘ editor_script‘ e ‘ editor_style‘, respectivamente. Quanto às dependências, adicionei alguns dos pacotes mais básicos para o script para garantir que nosso script de bloco seja carregado na ordem correta. Quanto ao estilo do editor, usar ‘ wp-edit-blocks‘ é uma boa dependência para evitar que seus estilos sejam substituídos.

E por fim por se tratar de um bloco dinâmico, precisamos também adicionar o render_callbackargumento ‘ ‘, apontando para uma função que é responsável por renderizar o bloco no frontend.

Por fim, definimos a função de renderização. Obtemos dois parâmetros para o retorno de chamada da função; uma matriz de atributos do bloco e o conteúdo interno (não usado neste bloco). Eu simplesmente retornarei alguma string fictícia. Voltaremos e detalharemos a função de renderização mais tarde. Lembre-se de retornar uma string, não echo.

function awp_gutenberg_slider_render($attributes, $content) {
    return 'Slider render comes here.';
}

Voltaremos à função de renderização do PHP no final deste tutorial. Agora é hora de passar para o Javascript!

Registre um bloco personalizado do Gutenberg em Javascript

Vamos abrir nosso block-slider.jsarquivo fonte. Neste ponto, iniciarei o script (npm run start) para transformar tudo o que fizermos neste arquivo no arquivo de compilação à medida que avançamos. Precisamos registrar o bloco usando [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/)(). Confira o link para ver todos os argumentos possíveis.

Como decidimos register_block_type()no PHP, nosso bloco se chama awp/slider. Também queremos adicionar dois atributos ao bloco, conforme mencionado anteriormente: um para o ID do termo selecionado e outro para o número de slides.

Eu gosto de adicionar a funcionalidade de alinhamento de blocos também. Ele será adicionado automaticamente adicionando ‘ align‘ ao supportsobjeto. Se você quiser todos os alinhamentos de bloco, basta definir aligncomo true. No entanto, um controle deslizante alinhado à esquerda ou à direita não faz muito sentido, então definirei os tipos específicos de alinhamentos de bloco que este bloco suporta: "Alinhar ao centro" (‘ center‘), "Largura ampla" (‘ wide‘) e " Largura total" (‘ full‘) Além disso, para definir um alinhamento padrão e torná-lo acessível a partir do PHP, adiciono ‘ align‘ como atributo ao nosso bloco.

Defino o argumento do bloco editpara um componente separado que criaremos a seguir. E finalmente a savefunção simplesmente retorna null, pois este é um bloco dinâmico.

Precisamos definir o componente para a editpropriedade. Antes do código de registro eu defino um componente de função BlockEditque simplesmente renderiza a dive a Placeholdercom algum texto fictício.

[Placeholder](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/placeholder)é um bom componente para renderizar uma área para configurações – e não necessariamente para a renderização real de um bloco. Dentro do Placeholdercomponente é onde renderizamos uma lista de termos para escolher.

Neste ponto, nosso bloco deve estar disponível no WordPress Gutenberg! Vamos criar um novo post, adicionar um novo bloco e encontrar nosso bloco dentro da categoria Comum. Esta é a aparência do nosso bloco atualmente:

Adicionando configurações do Inspetor

Vamos adicionar algumas configurações ao Inspetor (barra lateral direita do editor). Como mencionado, nosso bloco tem apenas uma configuração; número de slides. É aqui que eu recomendo que você adicione mais configurações para o seu bloco de controle deslizante. Lembre-se de registrar atributos para cada configuração adicionada.

Para adicionar algo ao Inspector usamos o componente [InspectorControls](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inspector-controls)( wp.blockEditor). Dentro nós renderizamos um [PanelBody](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/panel#panelbody)( wp.components) para adicionar uma nova seção recolhível. Em seguida, simplesmente renderizamos um [RangeControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/range-control)( wp.components) para criar uma configuração de entrada para escolher o número de slides. Definimos o mínimo como 1 e o máximo como 10. Conectamos o evento valueand onChangeao atributo numSlides.

Com o código acima, devemos agora obter uma boa seção com um controle deslizante de intervalo para definir o número de slides.

Mais uma vez, recomendo que você brinque adicionando mais configurações ao seu controle deslizante. A próxima etapa é criar o elemento para renderizar uma lista de categorias para escolher.

Criando um componente de seleção de categoria

Para manter nosso código organizado e reutilizável, vamos criar o componente seletor de categoria em um arquivo separado. Dentro da pasta build eu crio um novo arquivo awp-category-picker.js.

Dentro deste arquivo, definimos um componente que percorrerá todas as categorias atualmente no WordPress e as renderizará de alguma forma. Para obter categorias, precisamos envolvê-lo dentro de um chamado componente de ordem superior, que fornecerá ao nosso componente o que precisamos por meio de adereços. Para isso vamos usar [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect). Dentro withSelectpodemos fazer um pedido para buscar todas as categorias no WordPress usando o seletor de loja [select](https://developer.wordpress.org/block-editor/packages/packages-data/#select)(). Podemos usar:

para buscar todos os termos no slug de taxonomia fornecido. Se você não estiver familiarizado com os componentes e seletores de ordem superior no WordPress Gutenberg, tenho uma postagem que explica esse conceito com mais detalhes: Criar um bloco personalizado do Gutenberg – Parte 10: Buscando postagens e componentes de ordem superior.

Como precisamos exportar um componente desse arquivo, colocamos a combinação de withSelecte nosso componente definido na export defaultinstrução. Nosso CategorySelectcomponente simplesmente retorna uma div com algum texto fictício para que possamos ver que funciona. O withSelectdeve fornecer o prop ‘ terms‘ to CategorySelect. Eu adicionei um console.log()neste prop para que possamos ver que funciona.

A última coisa que precisamos fazer é importar e usar esse componente seletor de categoria em nosso bloco personalizado.

De volta block-slider.js, primeiro precisamos importar o componente no topo do arquivo. E dentro do nosso Placeholdercomponente nós simplesmente renderizamos o componente.

Com o código acima, seu bloco agora deve renderizar a div do CategorySelectcomponente. Se você abrir o Console em seu navegador, também deverá ver alguns logs. Lembre-se de que withSelecté uma consulta assíncrona, o que significa que pode renderizar várias vezes. A(s) primeira(s) vez(es) que os termos prop são null. Mas o(s) último(s) log(s) deve(m) terminar com uma série de termos de categoria.

Excelente! Vamos continuar trabalhando com nosso CategorySelectcomponente e fazer com que ele realmente renderize a lista de termos permitindo que o usuário selecione um!

Renderizando uma lista de termos para escolher

Há muitas maneiras de renderizar uma lista de opções em que o usuário pode selecionar um item. Se você quiser algo realmente simples, poderá renderizar um menu suspenso de seleção padrão ([SelectControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/select-control)). Depende inteiramente de você. Optei por uma abordagem mais limpa e agradável usando [MenuGroup](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-group)( wp.components) e [MenuItem](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-item)( wp.components).

Dentro de um MenuGroupcomponente, precisamos percorrer o props.termsarray e, para cada item, queremos exibir um MenuItemcomponente renderizando o nome do termo. E é claro que só queremos renderizar isso se props.termsrealmente contiver algo (solicitação assíncrona, lembra?).

Dei ao MenuGroupcomponente uma classe personalizada, pois precisaremos direcionar isso com CSS. E eu configurei o suporte rolepara MenuItem‘ menuitemradio‘ para garantir que apenas um possa ser escolhido de cada vez. Por padrão, funcionam como checkboxes, permitindo a escolha de vários itens.

Com o código acima, nosso bloco deve agora (após um pequeno segundo) renderizar uma boa lista de todas as categorias em sua instância do WordPress.

Você pode notar que nosso bloco se expandirá para conter todas as categorias. Se estivermos em uma instância do WordPress com muitas categorias, isso rapidamente se tornará um problema. Queremos ter certeza de que o seletor é um contêiner de altura máxima que recebe uma barra de rolagem vertical se houver muitas categorias. É aqui que entra nosso arquivo CSS.

Em nosso editor-block-slider.cssarquivo adicione:

.awp-categoryselect div {
    max-height: 200px;
    overflow: hidden scroll;
    border: 1px solid #b3bcc0;
}

Este CSS tem como alvo o interior do divnosso MenuGroupe garante que nunca ultrapasse 200px. Se o conteúdo MenuGroupficar maior (mais categorias), ele mostrará uma barra de rolagem vertical. Este é o mínimo de CSS para o nosso bloco, mas é claro que você pode adicionar mais CSS se quiser.

A última coisa que precisamos corrigir em nosso seletor de categoria é a funcionalidade de mostrar o item selecionado atualmente e permitir que o usuário selecione um termo da lista. Para isso precisamos passar alguns adereços para este componente do nosso bloco.

Em block-slider.jsnós precisamos passar o termo selecionado atual (valor do atributo termId) e uma função para atualizar o termo selecionado (setAttributes) como props para nosso componente seletor de categoria.

No código acima na linha #6definimos uma função que simplesmente atualiza o atributo termId. Passamos este nome de função como prop para CategorySelectat line #17. E na linha #16passamos o valor atual de termId. Com podemos atualizar nosso CategorySelectcomponente para refletir o item escolhido, e permitir que o usuário realmente escolha um termo.

De volta awp-category-picker.js, adicionamos alguns novos adereços ao MenuItem. Retornamos trueor falsepara a prop isSelectedse o ID do termo atual é ou não o mesmo que o atual selecionado. Iniciamos a selectTermfunção no onClickevento, passando o termo ID. E para tornar visual o item selecionado, adicionamos condicionalmente um ícone antes de cada item.

Com isso, nosso seletor de categoria deve ficar assim:

A lista deve marcar claramente o termo selecionado com um ícone de verificação, e você pode clicar em qualquer termo para selecioná-lo.

Isso foi tudo para a parte do editor e do Javascript! O que resta agora é a renderização do frontend, que faremos em PHP.

Renderize o bloco dinâmico em PHP

Antes de mergulharmos na função de renderização, vamos cuidar de algumas coisas primeiro.

Primeiro, precisamos enfileirar o script cycle2 no frontend para que nosso código deslizante realmente se transforme em um controle deslizante. Fazemos isso com uma função simples ligada a wp_enqueue_scripts. Ajuste o abaixo se você optou por outro script de controle deslizante.

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'cycle2-slider-js', 
        get_template_directory_uri(). '/assets/js/jquery.cycle2.min.js', 
        ['jquery'], 
        '', 
        true
    );
});

Em segundo lugar, queremos retornar à register_block_type()chamada da função. Quando lidamos com blocos dinâmicos, definitivamente devemos adicionar um novo argumento; attributes. Neste argumento definimos todos os atributos que definimos registerBlockTypeem Javascript, incluindo seus padrões. Se não o fizermos, nem todos os atributos estarão disponíveis em nosso retorno de chamada de renderização. Se um atributo foi deixado inalterado no editor de blocos, o atributo e seu valor não estarão disponíveis no array de atributos no PHP. Então eu recomendo que você sempre tenha o cuidado de adicionar o attributesarray à função PHP register_block_type()quando você trabalha com blocos dinâmicos. Para o nosso bloco ficaria assim:

Agora voltamos à nossa função de renderização de retorno de chamada awp_gutenberg_slider_render(). A saída depende completamente de você, especialmente se você optou por usar outro script de controle deslizante. O abaixo é um exemplo simples.

A ideia principal é verificar se um termo foi escolhido ou não ($attributes['termId']). Se estiver preenchido, criamos um [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)()com argumentos para o número de posts ($attributes['numSlides']) e o ID da categoria selecionada. Em seguida, é uma questão de gerar o HTML adequado para o cycle2 funcionar, fazer um loop sobre as postagens e exibir suas imagens em destaque como slides.

Observe como eu adiciono a classe de alinhamento de bloco adequada na linha #12. O resultado deve ser um controle deslizante das imagens em destaque. Tenha em mente que este é um exemplo básico que tem algumas falhas. Por exemplo, buscamos os últimos três posts da categoria selecionada. Mas supondo que um deles não tenha uma imagem em destaque, o controle deslizante exibirá apenas duas postagens.

A coisa importante a lembrar é retornar uma string e não ecoá-la. Eu também recomendo usar algum tipo de funcionalidade de modelagem em seu tema para renderizações de blocos dinâmicos como esses. Pode rapidamente tornar-se confuso consertar e construir HTML como uma string.

Palavras finais

Este tutorial mostrou como criar um bloco WordPress Gutenberg dinâmico personalizado onde você renderiza seu conteúdo de front-end em PHP. E você viu como usar o componente de ordem superior withSelectpara consultar todos os termos de categoria e um método para exibir uma lista selecionável.

Todo o código acima é escrito o mais simples possível. Eu apenas adicionei o mínimo absoluto de configurações. O controle deslizante funciona, mas geralmente você quer mais – por exemplo, fazer os links dos slides, mostrar os títulos das postagens, as setas do controle deslizante ou a opção de personalizar a velocidade ou outras configurações do controle deslizante. A ideia é mostrar o básico e facilitar a extensão, a construção e a mudança para atender às necessidades do seu projeto.