claude-plugins/wordpress/skills/jetengine/references/dynamic-content.md

# JetEngine — Dynamic Content, Macros e Profile Builder

## Dynamic Tags no Elementor

### Categorias de Dynamic Tags JetEngine

| Categoria | Tags Disponíveis |
|-----------|-----------------|
| **Post** | Post Title, Post URL, Post Date, Post Author, Featured Image, Post Terms |
| **Meta** | Meta Field (qualquer campo JetEngine) |
| **User** | User Name, User Email, User Role, User Meta |
| **Relations** | Relation Field (conteúdo relacionado) |
| **Options** | Option Field (JetEngine Global Options Pages) |
| **Macros** | JetEngine Macros (ver secção abaixo) |
| **Query** | Query Variable (parâmetros URL) |

### Usar Meta Field Tag

```
Elemento Elementor > Campo de texto > ícone Dynamic Tags
→ JetEngine > Meta Field
→ Seleccionar meta key name
→ Field Type: auto / text / image / url / ...

Para imagens (campo tipo media):
→ Field Type: Image
→ Image Size: thumbnail / medium / large / full

Para URLs em botões:
→ Link > Dynamic Tag > Meta Field > Field Type: URL
```

### Tags em CSS Custom (background, cores)

```
Elemento > Style > Background > Dynamic Tag
→ Meta Field → campo cor HEX
→ Útil para cards coloridos por categoria
```

---

## Macros

### Macros Built-in

```
%current_user_id%               # ID do utilizador logado
%current_user_name%             # Nome do utilizador
%current_user_email%            # Email do utilizador
%current_post_id%               # ID do post actual
%current_post_type%             # Post type do post actual
%queried_object_id%             # ID em arquivo/single
%queried_object_slug%           # Slug em arquivo/single
%request_field|param_name%      # Parâmetro URL: ?param_name=valor
%current_meta|field_name%       # Meta field do post actual
%user_meta|field_name%          # Meta field do utilizador logado
%current_taxonomy|tax_name%     # Taxonomy do post actual
%current_timestamp%             # Unix timestamp actual
%site_url%                      # URL do site
```

### Usar Macros em Query Builder

```
Exemplo: Listar imóveis favoritos do utilizador
Meta Query:
├── Field: favorito_de (campo que guarda array de IDs de utilizadores)
├── Operator: LIKE
└── Value: %current_user_id%

Exemplo: Listar items criados pelo utilizador
Meta Query:
├── Field: cct_author_id (campo automático do CCT)
├── Operator: =
└── Value: %current_user_id%
```

### Macros em Textos

```
Texto: "Bem-vindo, %current_user_name%!"
→ Em runtime: "Bem-vindo, João Silva!"

Em Heading Widget: activar Dynamic Tag > JetEngine Macros
→ Escrever a macro no campo Macro Value
```

### Criar Macro Custom (PHP)

```php
<?php
// Registar macro custom
add_filter('jet-engine/listings/macros-list', function($macros) {
    $macros[] = [
        'id'    => 'minha_macro',
        'name'  => 'Minha Macro Custom',
        'args'  => [], // parâmetros opcionais
    ];
    return $macros;
});

add_filter('jet-engine/listings/macros-result', function($result, $macro, $args) {
    if ($macro === 'minha_macro') {
        // Lógica da macro
        $result = 'valor calculado';
    }
    return $result;
}, 10, 3);
```

---

## Conditional Fields (Campos Condicionais)

### Em Meta Boxes

```
Campo B só aparece quando Campo A = "sim"

Meta Box > Campo B > Conditions:
├── Field: nome_campo_a
├── Operator: =
└── Value: sim
```

### Em Listing Templates (Visibility)

```
Elemento Elementor > Advanced > JetEngine Conditions:
├── Condition: Meta Field | Equals | "featured"
└── Effect: Show / Hide
```

---

## Global Options Pages

Para configurações globais do site (telefone, email, horários, redes sociais).

### Criar Options Page

```
JetEngine > Options Pages > Add New
├── Page Title: Informações Globais
├── Slug: informacoes-globais
└── Campos: Meta Box associado
```

### Usar em Elementor

```
Dynamic Tag > JetEngine > Option
→ Seleccionar Options Page
→ Seleccionar campo

Exemplo: footer com telefone dinâmico
→ Options Page: Informações Globais > campo: telefone
→ Editar telefone em 1 lugar, actualiza em todo o site
```

---

## Profile Builder

Sistema de áreas de conta para utilizadores logados.

### Estrutura

```
JetEngine > Profile Builder
├── Pages (áreas da conta):
│   ├── Dashboard (página principal)
│   ├── Submissões (posts do utilizador)
│   ├── Favoritos
│   ├── Configurações (editar perfil)
│   └── [custom pages]
├── Access Rules:
│   ├── Login Required: YES
│   ├── User Roles: subscriber / author / ...
│   └── Redirect não-logados: página de login
└── Profile Menu Widget (Elementor)
```

### Criar Página de Perfil

```
1. JetEngine > Profile Builder > Add Page
   Nome: Dashboard | Slug: dashboard
   Template: Criar com Elementor

2. No Template, usar Dynamic Tags:
   → User Name, User Email, User Avatar
   → Query Builder filtrado por %current_user_id%

3. Adicionar Profile Menu Widget ao header/sidebar
   → Mostra links para cada página do perfil
   → Altera links consoante se está logado ou não
```

### Submissão de Conteúdo por Utilizadores

```
JetFormBuilder + Profile Builder:
1. Criar formulário com acção "Create Post" (CPT)
2. Acção: Set Author = Current User
3. Colocar formulário na página de perfil
4. Query Builder na página de listagem: autor = current_user_id
```

### Editar Perfil com JetFormBuilder

```php
// JetFormBuilder Form:
// Acção: Update User
// Campos mapeados:
// ├── first_name → user first_name
// ├── last_name  → user last_name
// ├── email      → user email
// └── bio_custom → user_meta: bio_custom

// Pre-fill automático: activar "Use data from:" → Current User
```

---

## Conditional Content por Utilizador

### Mostrar Conteúdo Só a Logados

```
Elementor > Advanced > JetEngine Conditions:
Condition: Is User Logged In | Equals | True
Effect: Show (esconde elemento para não logados)
```

### Por Role

```
Condition: User Role | Contains | administrator
Effect: Show (só admins vêem este bloco)
```

### Por Meta do Utilizador

```
Condition: User Meta | Field: plano_subscricao | Equals | premium
Effect: Show (só utilizadores premium vêem este conteúdo)
```

---

## Repeater em Frontend

### Listar Items de um Repeater

```
Meta Box com campo Repeater "galeria_destaques":
├── Sub-campo: imagem (media)
├── Sub-campo: titulo (text)
└── Sub-campo: link (url)

Em Listing Template:
Adicionar widget "Dynamic Repeater"
→ Source: Meta Field → galeria_destaques
→ Criar template para cada item do repeater
```

---

*JetEngine Dynamic Content | Descomplicar® | 18-02-2026*