# JetEngine — Query Builder e Listings

## Query Builder Avançado

### Tipos de Query e Configuração

#### Query Posts

```
Campos principais:
├── Post Type: CPT ou post/page
├── Post Status: publish / draft / any
├── Posts per page: N (ou -1 para todos)
├── Order: ASC / DESC
├── Order By: date / title / menu_order / meta_value / meta_value_num / rand
│   └── Se meta_value: seleccionar meta key
├── Meta Query (múltiplas condições):
│   ├── Field: meta key name
│   ├── Type: CHAR / NUMERIC / DATE
│   ├── Operator: = / != / > / < / BETWEEN / LIKE / IN / NOT IN / EXISTS
│   └── Value: valor ou macro (%current_user_id%)
└── Tax Query:
    ├── Taxonomy: seleccionar taxonomy
    ├── Operator: IN / NOT IN / AND
    └── Terms: valores ou relação dinâmica
```

#### Query CCT

```
Campos principais:
├── Content Type: seleccionar CCT
├── Items per page: N
├── Order By: qualquer coluna do CCT
├── Filters (equivalente a Meta Query):
│   ├── Field: coluna do CCT
│   ├── Operator: = / != / > / LIKE / IN
│   └── Value: valor ou macro
└── Show items only for current user: activar para perfis
```

#### Query Relação

```
Objetivo: listar items relacionados ao post/item actual
├── Relation: seleccionar relação criada no JetEngine
├── Get children of: post actual / ID específico / macro
└── Post Type: tipo dos items relacionados
```

### Meta Query com Macros

```
Exemplo: listar projectos do utilizador logado
Meta Query:
├── Field: cliente_user_id
├── Operator: =
└── Value: %current_user_id%

Exemplo: listar items de hoje
Meta Query:
├── Field: data_evento (timestamp)
├── Type: NUMERIC
├── Operator: >=
└── Value: %current_timestamp%
```

### Combinar Múltiplas Condições

```
Relation: AND (todas as condições verdadeiras)
         OR  (pelo menos uma verdadeira)

Exemplo: imóveis em Lisboa com preço < 300k
Tax Query 1: Localização = Lisboa
Meta Query 1: Preço < 300000
Relation: AND
```

---

## Listing Grid — Configuração Detalhada

### Criar Listing Template

```
JetEngine > Listings > Add New
Nome: [CPT]-listing-card
Listing From: Posts / Terms / Users / CCT
Post Type: [seleccionar]
Editar com Elementor:
├── Usar Dynamic Tags em todos os campos
├── Post Title Widget → ou Text Widget com dynamic tag
├── Meta Field → adicionar Dynamic Tag > JetEngine > Meta Field
├── Post Featured Image → ou Image Widget com dynamic tag
└── Button → URL com dynamic tag > Post URL
```

### Listing Grid Widget — Parâmetros

```
Listing Item: [seleccionar template]
Use Custom Query: YES → seleccionar Query Builder
Items per page: 12 (padrão)
Not Found Text: "Sem resultados"
Loader: activar para UX com filtros
Columns: 1/2/3/4 (responsivo)
Equal Columns Height: YES para cards uniformes
```

### Paginação

```
Listing Grid > Pagination:
├── Type: Default WP / Load More / Infinity Scroll
├── Load More Button Text: "Carregar mais"
├── On Scroll: activar para infinity
└── Starting From: 1
```

### Ordenação Dinâmica (Frontend)

```
Adicionar widget: JetSmartFilters > Sorting
├── Ligar ao mesmo Listing Grid
└── Opções: Date ASC/DESC, Title, Price, Custom Field
```

---

## Listing Map

### Configuração

```
1. Activar Google Maps API Key:
   JetEngine > Settings > Google Maps API Key

2. Criar Meta Box com campo tipo Map no CPT
   (O utilizador define latitude/longitude via picker no editor)

3. Criar Listing Template tipo: Map Marker
   Adicionar: Post Title, info a mostrar no popup

4. Adicionar widget Listing Map ao Elementor
   ├── Listing Item: [marker template]
   ├── Use Custom Query: YES
   ├── Map Field: seleccionar campo coordenadas
   └── Map Options: zoom, altura, cluster
```

### Mapa + Listing Grid Sincronizados

```
Adicionar os dois widgets na mesma página
Ligar ao mesmo Query Builder
Activar "Synchronize with Listing Grid": YES no Map
→ Ao fazer hover no card, destaca pin no mapa
→ Ao fazer hover no pin, destaca card na lista
```

---

## Archive e Single Templates

### Single CPT com Elementor (JetThemeCore ou Elementor Pro)

```
JetThemeCore > Templates > Add New > Single
Conditions: Post Type = [meu_cpt]
Editar com Elementor usando Dynamic Tags

OU

Elementor > Templates > Theme Builder > Single
Conditions: igual
```

### Archive Page

```
JetThemeCore > Templates > Add New > Archive
Conditions: Post Type Archive = [meu_cpt]
Adicionar:
├── Archive Title Widget
├── Listing Grid Widget (sem Custom Query — usa WP_Query do arquivo)
└── JetSmartFilters (ligado ao mesmo archive)
```

---

## JetSmartFilters — Integração Avançada

### AJAX Reload vs Full Page

```
Provider: Listing Grid → AJAX (sem reload de página)
Provider: Archive → Pode ser AJAX ou URL based
Provider: WooCommerce → AJAX
```

### URL Based Filters (SEO Friendly)

```
JetSmartFilters > Filters > Edit
├── Query Variable: activar
├── URL Based: activar
└── Clean URL: activar

Resultado: site.pt/imoveis/?cidade=Lisboa&preco=200000-400000
(Em vez de AJAX puro — melhor para SEO e partilha de URL)
```

### Hierarquical Taxonomy Filter

```
Exemplo: País → Distrito → Concelho
├── Criar taxonomia com hierarquia
├── Filtro: Checkboxes com hierarquia activada
└── "Show children of selected": activar
```

---

*JetEngine Query & Listings | Descomplicar® | 18-02-2026*