Macros para Query Builder

Compreender como funcionam as macros do JetEngine é importante para obter flexibilidade na construção de consultas de qualquer complexidade.

Uma macro é um pedaço de uma string que é substituído por um determinado valor dependendo da finalidade da macro. Em outras palavras, uma macro é uma variável que pode retornar valores diferentes com base no contexto. Por exemplo, a macro %current_id% retorna o ID do objeto atual. Na única página de uma postagem, a macro %current_id% retorna o ID dessa postagem.

Suponha que nosso objetivo seja exibir a postagem atual nos resultados da consulta. Como precisamos consultar postagens, criamos uma Posts Query . O campo Post In nas configurações da consulta espera o ID de uma postagem.

Portanto, se usarmos a macro %current_id% no campo Post In de uma Consulta de Postagens e visualizarmos os resultados de uma determinada postagem, veremos essa postagem nos resultados da consulta.

Em nosso exemplo, visualizamos os resultados de uma postagem chamada “Como cortar flores”, que tem o ID ‘2749’. Se quiséssemos incluir aquela postagem específica nos resultados da consulta, poderíamos escrever o ID manualmente.

A macro Current ID também retorna o valor ‘2749’ quando usada no post “Como cortar flores”. No entanto, esta é uma solução dinâmica que nos permite evitar a criação manual de inúmeras consultas duplicadas para diferentes postagens.

Da mesma forma, é possível usar a macro ID atual em outros campos de consulta personalizados que suportam IDs de postagem. 

No entanto, nem todas as macros retornam um único ID. Algumas macros retornam uma lista de IDs separados por vírgulas – por exemplo, a macro Termos atuais retorna a lista de IDs dos termos de postagem atuais (por exemplo, ‘2234, 2342, 4958’). Outras macros retornarão valores de um tipo diferente. Você encontrará uma descrição de cada macro e o valor que a macro retorna em nosso Guia de Macros .  

Para usar macros do Query Builder , comece criando uma consulta personalizada em WordPress Dashboard > JetEngine > Query Builder > Add New . 

Existem diferentes tipos de consultas: Consulta de Posts, Consulta de Termos, Consulta de Usuários, Consulta de Comentários, etc. A escolha de uma consulta personalizada depende dos itens que serão consultados. Por exemplo, uma Consulta de Postagens deve ser escolhida para consultar uma lista de postagens. Se os usuários devem ser consultados, a Consulta de Usuários deve ser selecionada. O tipo de consulta também determina quais objetos serão retornados nos resultados da consulta (a Consulta de Postagens retornará uma lista de postagens, a Consulta de Usuários retornará a lista de usuários, etc.).

Cada campo nas configurações da consulta possui uma descrição que informa qual valor deve ser inserido no campo. A maioria dos campos suporta macros, mas certifique-se de usar macros de acordo com sua finalidade e de acordo com o valor que a macro retorna (verifique Noções básicas de macros para obter mais informações).

A seguir, abordaremos os casos mais populares em que macros do Query Builder são utilizadas.

Limitando os resultados da consulta à postagem atual ou excluindo a postagem atual dos resultados da consulta

O ID da postagem atual pode ser recuperado com a ajuda da macro Current ID . Use-o para mostrar apenas a postagem atual em um widget que suporta consultas personalizadas do JetEngine (por exemplo, em um Map Listing ). 

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem.

Em seguida, prossiga para a guia Postagem e página de configurações e insira a macro ID atual no campo Postar em .

” alt=”usando a macro de identificação atual no construtor de consultas” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/using-current-id-macro-in-query-builder_2x.png” />Se você precisar excluir a postagem atual dos resultados da consulta, coloque a macro ID atual no campo Postagem não recebida em vez do campo Postagem em .

” alt=”excluir a postagem atual dos resultados da consulta” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/exclude-current-post-from-the-query-results_2x.png” />Após salvar a consulta, crie um modelo de listagem para o mesmo tipo de postagem e exiba a listagem em uma única página de postagem com a ajuda da grade de listagem. Aplique a consulta criada na Grade de Listagem conforme descrito na etapa Aplicando a Consulta Criada .

Exibir postagens na página de arquivo de taxonomia

Para consultar postagens pelo termo atual, use a macro Termo consultado . A macro retorna o ID do termo atual e pode ser usada na aba Consulta Fiscal de uma Consulta de Postagens para exibir postagens nas páginas do arquivo de taxonomia. 

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem.

” alt=”especifique o tipo de postagem nas configurações da consulta de postagens” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/specify-post-type-in-the-settings-of-posts-query_2x.png” />Em seguida, prossiga para a guia de configurações Consulta Fiscal .

” alt=”mostrando postagens na página de arquivo de taxonomia” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/showing-posts-on-the-taxonomy-archive-page_2x.png” />Em primeiro lugar, selecione a taxonomia necessária. Em seguida, selecione a opção “ID do termo” no menu suspenso Campo porque estamos comparando o ID do termo atual com os IDs dos termos na taxonomia. No campo Termos , selecione a macro do termo consultado – ela recupera o ID do termo atual. Por fim, selecione o operador “In” Compare . Salve a consulta. 

Esta consulta personalizada substitui a opção “Usar como modelo de arquivo” nas configurações do widget Listing Grid .

” alt=”usar como configuração de modelo de arquivo na grade de listagem” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/use-as-archive-template-setting-in-listing-grid_1x.png” />Ele também fornece uma maneira de separar postagens na página de arquivo de taxonomia por tipo de postagem – basta criar uma nova consulta para cada novo tipo de postagem que deve ser exibido separadamente. Aplique a consulta criada na Grade de Listagem conforme descrito na etapa Aplicando a Consulta Criada .

Exibir postagens relacionadas por termos na página de postagem única

Para exibir postagens conectadas aos termos da postagem atual, use a macro Termos atuais . A macro retorna uma lista de IDs de termos conectados à postagem atual. Ele pode ser usado na aba Consulta Fiscal de uma Consulta de Postagens para exibir postagens relacionadas aos mesmos termos da postagem atual.

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem.

Em seguida, prossiga para a guia de configurações Consulta Fiscal .

Em primeiro lugar, selecione a taxonomia necessária. Em seguida, selecione a opção “ID do termo” no menu suspenso Campo porque estamos comparando os IDs listados no campo Termos com os IDs dos termos na taxonomia. No campo Termos , selecione a macro Termos atuais . Por fim, selecione o operador “In” Compare . Salve a consulta. 

Após salvar a consulta, crie um modelo de listagem para o mesmo tipo de postagem e exiba a listagem em uma única página de postagem com a ajuda da grade de listagem. Aplique a consulta criada na Grade de Listagem conforme descrito na etapa Aplicando a Consulta Criada .

Além disso, você pode verificar Como exibir postagens relacionadas no WordPress usando Listing Grid .

Exibir postagens na página de arquivo de resultados de pesquisa

A macro Variável de consulta pode ser usada para exibir postagens na página Resultados da pesquisa. 

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem.

Em seguida, selecione a macro Query Variable para o campo Search Keyword e especifique o nome da variável – ‘ s ‘.

Se alguém usar a função de pesquisa para pesquisar “flores”, a consulta retornará postagens do tipo de postagem especificado que correspondam em título, conteúdo ou trecho. Aplique esta consulta ao widget Grade de listagem no modelo de arquivo de resultados de pesquisa para fazer com que a listagem se ajuste à palavra-chave pesquisada.

Esta consulta personalizada também suporta o Ajax Search do plugin JetSearch .

Exibir postagens com o mesmo valor meta da postagem atual

Use a macro Valor meta atual para exibir postagens que tenham o mesmo valor em um determinado meta campo que a postagem atual.

Supondo que exista um metacampo de Rádio chamado ‘Hot Deals’ em um tipo de postagem de Propriedades. Tem duas opções – ‘sim’ e ‘não’. Na única página de uma postagem de propriedade, queremos exibir outras propriedades que tenham a mesma opção selecionada no metacampo ‘Hot Deals’. Por exemplo, a postagem ‘Rainforest Guest House’ tem a opção ‘sim’ selecionada.

” alt=”postagem de propriedade com um metacampo de rádio selecionado” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/property-post-with-a-radio-meta-field-selected_2x.png” />O objetivo é exibir outras propriedades onde a opção ‘sim’ foi marcada e excluir o post atual dos resultados da consulta. 

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem.

” alt=”especifique o tipo de postagem nas configurações de postagens” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/specify-post-type-in-the-settings-of-posts-query_2x.png” />Em seguida, prossiga para a guia Meta Query das configurações e adicione uma nova meta cláusula.

” alt=”consulta por meta valor atual” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/query-by-current-meta-value_2x.png” />Para o campo Chave/nome do campo , selecione a macro de metacampo JetEngine . Uma vez selecionado, pressione a macro novamente para selecionar o metacampo necessário e ‘Nome/chave/ID do campo’ no menu suspenso Retorno .

” alt=”meta cláusula na consulta de postagens do jetengine” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/meta-clause-in-posts-query-of-jetengine_2x.png” />Depois disso, defina o operador Comparar como “Igual (=)” e selecione a macro valor meta atual no campo Valor . Pressione na macro para especificar a meta-chave. A meta-chave pode ser copiada do campo Nome/ID das configurações do meta-campo.

A macro Valor meta atual retorna o valor do meta campo especificado da postagem atual. Em seguida, usando as configurações da meta cláusula, ela é comparada com valores nos mesmos metacampos de outras postagens. Como resultado, a consulta personalizada retorna todas as postagens em que o valor meta é igual ao valor meta da postagem atual. 

Para excluir a postagem atual dos resultados da consulta, use a macro ID atual no campo Postagem que não está na guia Postagem e página das configurações de consulta personalizada.

Após salvar a consulta, crie um modelo de listagem para o mesmo tipo de postagem e exiba a listagem em uma única página de postagem com a ajuda da grade de listagem. Aplique a consulta criada na Grade de Listagem conforme descrito na etapa Aplicando a Consulta Criada .

Consultar postagens pelo metacampo Postagens

Usando o meta valor atual como macro de string, é possível exibir postagens selecionadas no meta campo Postagens da postagem atual.

Se a configuração Múltiplo estiver habilitada para o metacampo Postagens , o valor desse metacampo será salvo como uma matriz. A macro Valor meta atual como string permite transformar o valor em uma string e usá-lo no Query Builder . 

Crie uma consulta de postagens . Na guia Geral , especifique o mesmo tipo de postagem que foi selecionado nas configurações do metacampo Postagens .

Em seguida, prossiga para a guia Postagem e página de configurações e aplique o meta valor atual como macro de string no campo Postar em .

Uma vez aplicado, clique na macro novamente para especificar a meta-chave. A meta-chave pode ser copiada do campo Nome/ID das configurações do meta-campo.

Após salvar a consulta, crie um Listing Template para o tipo de post que foi selecionado nas configurações do metacampo Posts e exiba a listagem em uma única página de post com a ajuda da Listing Grid. Aplique a consulta criada na Grade de Listagem conforme descrito na etapa Aplicando a Consulta Criada . 

Dessa forma, as postagens selecionadas no metacampo Postagens da postagem atual podem ser exibidas como uma listagem no front end.

Exibir postagens de autoria na página Conta de um usuário

Usando a macro ID do usuário atual , é possível recuperar postagens criadas pelo usuário conectado no momento. 

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem em que as postagens devem ser recuperadas.

Em seguida, prossiga para a guia Autor das configurações de consulta personalizada. Para o campo ID do autor , selecione a macro ID do usuário atual .

A macro ID do usuário atual retorna o ID do usuário conectado no momento. Portanto, esta consulta personalizada pode ser usada para exibir postagens de autoria na página Conta. 

Para utilizar a consulta na página Conta, primeiro crie um Modelo de Listagem para o mesmo tipo de postagem; em seguida, coloque o widget Grade de listagem na página Conta, selecione o modelo de listagem e aplique a consulta conforme descrito na etapa Aplicando a consulta criada .

Exibir postagens de autoria na página de perfil público

A macro de ID do usuário consultado recupera o ID do usuário na página de perfil público criada no módulo Profile Builder do JetEngine . Use-o para exibir postagens de autoria do usuário consultado. 

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem em que as postagens devem ser recuperadas.

” alt=”especifique o tipo de postagem nas configurações da consulta de postagens” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/05/specify-post-type-in-the-settings-of-posts-query_2x.png” />Em seguida, prossiga para a guia Autor das configurações de consulta personalizada. Para o campo ID do autor , selecione a macro ID do usuário consultado .

Para utilizar a consulta na página de perfil público, primeiro crie um modelo de listagem para o mesmo tipo de postagem; em seguida, coloque o widget Grade de listagem em um modelo pertencente à página de perfil público, selecione o modelo de listagem e aplique a consulta conforme descrito na etapa Aplicando a consulta criada .

Exibir o autor da postagem atual

Crie uma consulta de usuários . Na guia Incluir/Excluir , encontre o campo Incluir que espera um ID ou IDs de usuários. Selecione a macro Post Author ID para este campo.

Quando colocada em uma única página de uma postagem, a consulta recuperará o usuário que é o autor da postagem atual. Para usar a consulta, primeiro, crie um modelo de listagem para usuários , coloque o widget/bloco Listing Grid na página ou modelo de postagem única, selecione o modelo de listagem criado e aplique a consulta conforme descrito na etapa Aplicando a consulta criada .

Exibir termos associados à postagem atual

A mesma macro de ID atual pode ser aplicada em uma consulta de termos para recuperar termos conectados à postagem ou produto atual. 

Crie uma consulta de termos . Na guia Geral de configurações, especifique a taxonomia necessária. No campo Object/Post IDs abaixo, precisamos incluir o ID do objeto, cujos termos devem ser recuperados. Para este campo, selecione a macro ID atual para buscar automaticamente o ID da postagem atual.

Para usar esta consulta, crie um modelo de listagem para a mesma taxonomia , coloque o widget/bloco Listing Grid na página ou modelo de postagem única, selecione o modelo de listagem criado e aplique a consulta conforme descrito na etapa Aplicando a consulta criada .

Exibir postagens adicionadas pelo usuário atual ao Data Store

A macro Get Store permite recuperar os IDs dos objetos adicionados pelo usuário conectado no momento ao Data Store especificado . Use este método para mostrar postagens que foram curtidas ou visitadas pelo usuário atual, dependendo das configurações do Data Store .

Crie uma consulta de postagens . Na guia Geral , especifique o tipo de postagem.

Em seguida, prossiga para a guia Postagem e página de configurações e selecione a macro Obter loja no campo Postar em .

Após salvar a consulta, crie um modelo de listagem para o mesmo tipo de postagem personalizado; colocar o widget/bloco Listing Grid na página onde os posts adicionados ao Data Store deverão ficar visíveis; selecione o modelo de listagem criado e aplique a consulta conforme descrito na etapa Aplicando a consulta criada .

Exibir usuários que gostaram da postagem atual

O item Obter usuários do armazenamento recupera os IDs dos usuários que adicionaram o item especificado ao Data Store . Um dos possíveis casos de uso desta macro é exibir usuários que “curtiram” a postagem atual. 

Crie uma consulta de usuários . Na guia Incluir/Excluir , encontre o campo Incluir que espera um ID ou IDs de usuários. Selecione a macro Obter usuários do item da loja para este campo. Uma vez aplicado, clique na macro novamente para abrir um pop-up com configurações adicionais. Selecione o Data Store necessário e especifique o Contexto – ‘Post’.

Quando colocada na única página de uma postagem, a consulta recuperará os usuários que adicionaram a postagem ao Data Store . Para usar a consulta, primeiro, crie um modelo de listagem para usuários , coloque o widget/bloco Listing Grid na página ou modelo de postagem única, selecione o modelo de listagem criado e aplique a consulta conforme descrito na etapa Aplicando a consulta criada .

Na maioria dos casos, a consulta personalizada retornará todos os itens quando uma macro foi aplicada incorretamente, um contexto não foi especificado ou nada foi encontrado para a seleção atual. Para fazer com que a consulta retorne 0 resultado nos casos em que nada foi encontrado, é necessário aplicar um valor fallback à macro. 

Um valor substituto é um valor que será aplicado quando nenhum resultado for encontrado. Os substitutos estão disponíveis para todas as macros. 

Vamos entender o uso de fallbacks por meio de um exemplo.

Imagine que queremos exibir postagens que também estejam conectadas às categorias da postagem atual, conforme descrito nesta etapa . Há uma nova postagem chamada ‘Postagem de teste’ que ainda não possui nenhum termo associado. Na única página dessa postagem, a consulta simplesmente retornará todas as postagens publicadas desse tipo de postagem em vez de retornar zero resultados.

Este não é o resultado desejado, então precisamos aplicar um valor substituto que será usado se a macro não encontrar nenhum resultado. 

Clique na macro adicionada para abrir um pop-up com configurações adicionais. Na parte superior do pop-up, pressione o botão Configurações avançadas para acessar as configurações avançadas da macro.

No campo Fallback , especifique um valor inexistente – por exemplo, um ID de termo inexistente como ‘999999’.

Agora, a consulta retorna 0 resultados, que é o comportamento desejado.

Você está livre para usar a consulta personalizada criada em qualquer widget que a suporte. O caso mais popular, entretanto, é aplicar a consulta criada em um widget Listing Grid . Abaixo, descreveremos como aplicar as consultas personalizadas do Query Builder no widget Listing Grid no Elementor e no bloco Listing Grid no Gutenberg (Block Editor).

Ajuste a listagem no Elementor

Vá para a página ou modelo onde deseja colocar a grade de listagem e abra-a no editor Elementor . 

Encontre o widget Listing Grid e coloque-o na página. Selecione o modelo de listagem necessário que você criou anteriormente. Defina todos os parâmetros na guia Geral para obter o resultado desejado.

A próxima etapa é ir para a guia Consulta Personalizada . Aqui, ative a opção Usar consulta personalizada e especifique a consulta personalizada selecionando aquela que você acabou de criar.

É isso. Agora, a listagem deve exibir itens de acordo com os resultados da consulta personalizada.

Ajuste a listagem em Gutenberg (Editor de Bloco)

Vá para a página ou modelo onde deseja colocar a Grade de Listagem e abra-a no editor Gutenberg . 

Encontre o bloco Listing Grid e coloque-o na página. Selecione o modelo de listagem necessário que você criou anteriormente. Defina todos os parâmetros na guia Geral para obter o resultado desejado.

A próxima etapa é ir para a guia Consulta Personalizada . Aqui, ative a opção Usar consulta personalizada e especifique a consulta personalizada selecionando aquela que você acabou de criar.