Como exibir elementos de matriz do endpoint da API REST usando o complemento de subconsulta

Antes de começar, verifique os requisitos do tutorial:

Elementor (versão gratuita) ou editor de blocos (Gutenberg)
Plug-in JetEngine instalado e ativado com o endpoint da API REST conectado

O complemento Sub Query permite recuperar elementos de array de uma propriedade de objeto pai. Use-o para buscar elementos de array em objetos passados em um endpoint da API REST e exibi-los convenientemente como uma listagem aninhada.

Conecte-se a um endpoint da API REST

Se você ainda não se conectou a uma API REST, navegue até WordPress Dashboard > JetEngine > JetEngine > REST API Endpoints e conecte seu endpoint.

Clique no botão “ Enviar solicitação ” para garantir que a solicitação seja enviada com sucesso e os dados sejam recuperados no formato correto. Não se esqueça de salvar este endpoint.

Configurar uma consulta personalizada para o endpoint da API REST

Aviso

Esta etapa é opcional. Se não precisar consultar o endpoint, você pode passar para a próxima parte do artigo. No entanto, criar uma consulta ajudará você a ver a estrutura de dados do endpoint.

Para criar uma consulta personalizada, vá para WordPress Dashboard > JetEngine > Query Builder > Add New para criar uma consulta personalizada para o endpoint conectado. Posteriormente, usaremos essa consulta para construir a listagem principal dos dados da API REST.

Nas configurações da consulta personalizada, selecione “Consulta API REST” como o tipo de consulta . Em seguida, especifique o endpoint no menu suspenso From Endpoint da seção Consulta da API REST. Se necessário, adicione mais cláusulas de consulta para restringir os resultados.

Salve a consulta e ative o botão Visualizar resultados para visualizar os dados recuperados pela consulta.

No nosso exemplo, recebemos uma lista de alunos e dados específicos associados a eles. Em cada objeto (aluno), existe uma propriedade de array “idiomas” contendo um objeto com três propriedades – “primeiro idioma”, “segundo idioma” e “terceiro idioma”.

Há também um array de “atividades extras” contendo apenas valores de string em vez de objetos.

Os elementos de ambas as matrizes podem ser exibidos como uma listagem aninhada com a ajuda do complemento Sub Query .

Baixe e instale o complemento SubQuery

Todos os complementos gratuitos para JetPlugins estão listados na página DevTools . Navegue até essa página, filtre os complementos por JetEngine e pesquise o complemento Sub Query . Clique no botão “ Baixar ” .

Depois, retorne ao Painel do WordPress > guia Plugins e pressione o botão “ Adicionar Novo ” para adicionar o complemento . Em seguida, ative o plugin.

Configure uma subconsulta para recuperar a matriz de objetos

Agora, usaremos a Sub Consulta para recuperar elementos do array de objetos.

Crie uma nova consulta personalizada em WordPress Dashboard > JetEngine > Query Builder > Add New . Dê um nome à consulta e escolha o novo tipo de consulta “Subconsulta” no menu suspenso correspondente.

Vá para o corpo da consulta, a seção Subconsulta .

A consulta destina-se a funcionar com listagens aninhadas. Isso significa que o Listing Template que será construído posteriormente com base nesta consulta será colocado dentro do Listing Template principal . A subconsulta recupera dados da propriedade do objeto pai e, em nosso caso de uso, o objeto pai é a listagem dos dados da API REST.

O primeiro campo obrigatório é o campo Propriedade do objeto pai . Espera o nome da propriedade pai de onde os dados devem ser recuperados. Nesta consulta, recuperaremos elementos do array da propriedade “idiomas” de um objeto API REST. Portanto, especificamos “idiomas” como o objeto pai para obter dados.

Agora, configure o esquema de itens para o item único do objeto Subconsulta. Nas configurações do esquema indicamos em quais campos cada item da Sub Consulta deve ser composto. É necessário preencher esses dados para ter acesso a esses elementos nas configurações de widgets/blocos. Portanto, adicione apenas as propriedades que serão exibidas na listagem aninhada, pois não é necessário usar todas as propriedades disponíveis no array.

O Nome da Propriedade define o rótulo da propriedade do item de consulta. Ele definirá como a propriedade inicial do objeto será rotulada nos resultados da consulta. A propriedade inicial do objeto especifica o nome real da propriedade da matriz. No nosso caso, é “primeira língua”.

Adicione quantas propriedades forem necessárias para construir o esquema do item de consulta. Uma vez feito isso, salve as alterações.

Configure uma subconsulta para recuperar a matriz de valores de string

Construiremos outra Sub Consulta para recuperar elementos do array “atividades extras”. Esta matriz consiste em valores de string em vez de objetos.

Crie uma nova consulta personalizada do tipo “Sub Consulta” e prossiga para as configurações da consulta.

Como propriedade do objeto pai , especificamos a propriedade “atividades extras”.

Vá para o esquema de itens .

Se a matriz contiver valores de string ou numéricos, será necessário definir uma única propriedade para armazenar o valor. A lista de elementos será preenchida automaticamente. Portanto, adicione apenas uma propriedade ao esquema e dê um nome a ela. Deixe o campo Propriedade Inicial do Objeto vazio.

Salve a consulta pressionando o botão correspondente.

Aviso

Os elementos dentro da matriz de objetos ‘idiomas’ também podem ser exibidos com a ajuda do retorno de chamada Get child element from object/array do widget/bloco Dynamic Field . Portanto, em vez de criar uma Subconsulta , é possível exibir cada elemento separado do array colocando o widget/bloco do campo Campo Dinâmico no modelo de listagem da API REST principal e aplicando o retorno de chamada para obter os elementos do array. No entanto, para exibir o tipo de array ‘atividades extras’, é altamente recomendável usar uma Sub Consulta .

Crie listagens aninhadas com base nas subconsultas

A próxima tarefa é construir uma listagem aninhada que produzirá os elementos dentro de nossos arrays. Na imagem abaixo, os itens “Idiomas” e “Atividade Extra” representam listagens aninhadas com base em subconsultas.

Crie o modelo de listagem no Elementor

Para criar uma nova listagem, navegue até WordPress Dashboard > JetEngine > Listings . Clique no botão “ Adicionar novo ” para abrir um pop-up de item de listagem de configuração .

Selecione “Query Builder” como fonte da listagem e encontre a subconsulta criada anteriormente no menu suspenso de consultas personalizadas. Dê um nome à listagem e clique no botão “ Criar item de listagem ” .

Procure o widget Campo Dinâmico e coloque-o no modelo. Como Fonte do widget, deixe a opção “Post/Term/User/Object Data”. Em seguida, abra o menu suspenso Campo de objeto e pesquise o nome da sua subconsulta. Abaixo do nome da consulta, há uma lista de elementos recuperados pela consulta. Usando esses elementos, crie o layout de sua listagem.

Não se preocupe se não vir nada na visualização, pois os elementos aparecerão assim que você colocar a listagem aninhada dentro da listagem principal.

Terminada a personalização, salve o modelo pressionando o botão “ Publicar/Atualizar ”.

Crie o modelo de listagem no Block Editor (Gutenberg)

Selecione “Query Builder” como fonte da listagem e encontre a subconsulta criada anteriormente no menu suspenso de consultas personalizadas. Dê um nome à listagem, selecione “Blocos (Gutenberg)” para a visualização da listagem e clique no botão “ Criar item de listagem ” .

Procure o bloco Campo Dinâmico e coloque-o no modelo.

Como Fonte do widget, deixe a opção “Post/Term/User/Object Data”. Em seguida, abra o menu suspenso Post Object e pesquise o nome da sua subconsulta. Abaixo do nome da consulta, há uma lista de elementos recuperados pela consulta. Usando esses elementos, crie o layout de sua listagem.

Não se preocupe se não vir nada na visualização, pois os elementos aparecerão assim que você colocar a listagem aninhada dentro da listagem principal.

Depois de concluir a personalização, salve o modelo.

Crie a listagem principal para exibir os resultados do endpoint

É hora de construir a listagem principal para mostrar o restante das propriedades do endpoint da API REST. Adicione uma nova listagem em WordPress Dashboard > JetEngine > Listings . Como Fonte de Listagem , selecione uma das opções: “REST API Endpoint” caso você não tenha criado uma consulta REST API ; “Query Builder” se você criou uma consulta REST API.

As mesmas configurações podem ser aplicadas à visualização Gutenberg (Editor de Bloco).

Se a origem do modelo de listagem for “Construtor de consultas”, encontre o nome da consulta personalizada no menu suspenso Campo de objeto e selecione qualquer um dos campos disponíveis. Se o campo não aparecer no menu suspenso, especifique-o manualmente no campo Objeto personalizado/campo Meta/ campo de entrada Chave de repetidor.

As mesmas configurações são aplicáveis à visualização Block Editor (Gutenberg).

Por último, encontre o widget/bloco Listing Grid e coloque-o no modelo. Use-o para exibir as listagens aninhadas criadas anteriormente.

Observe que não é necessário aplicar a Sub Consulta na aba Consulta Personalizada das configurações do widget/bloco Listing Grid . A listagem ainda recuperará dados da consulta personalizada, que é a origem do Listing Template .

Quando terminar, navegue até a página ou modelo onde a listagem com os dados da API REST deve estar visível e coloque a listagem principal nessa página. A listagem principal conterá listagens aninhadas que geram dados da propriedade do objeto pai.

Isso é tudo sobre o complemento Sub Query disponível gratuitamente como parte do plugin JetEngine para o seu site WordPress.