claude-plugins/wordpress/skills/elementor/SKILL.md

---
name: elementor
description: Desenvolvimento avançado com Elementor Pro e ecossistema Crocoblock. Cria widgets custom, configura Theme Builder, automatiza deploys, manipula _elementor_data via MySQL, REST API, Dynamic Tags e cache CSS.
---

# /elementor - Elementor Development

Desenvolvimento avançado com Elementor Pro e Crocoblock.

## Quando Usar

- Criar widgets Elementor customizados
- Configurar Theme Builder
- Desenvolver com Crocoblock (JetEngine, JetWooBuilder)
- Optimizar performance Elementor
- Troubleshooting Elementor

## Contexto NotebookLM

ANTES de executar, consultar notebooks para contexto especializado:

| Notebook | ID | Consultar quando |
|----------|-----|-----------------|
| WordPress e Elementor | 5be0d1a6 | Sempre |

```
mcp__notebooklm__notebook_query({
  notebook_id: "5be0d1a6-00f2-4cd9-b835-978cb7721601",
  query: "<adaptar ao contexto do pedido do utilizador>"
})
```

Integrar insights do NotebookLM nas recomendações e decisões.

---

## Estrutura Custom Widget

```php
<?php
/**
 * Custom Elementor Widget
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2026 Descomplicar®
 */

class Custom_Widget extends \Elementor\Widget_Base {

    public function get_name() {
        return 'custom-widget';
    }

    public function get_title() {
        return 'Custom Widget';
    }

    public function get_icon() {
        return 'eicon-code';
    }

    public function get_categories() {
        return ['general'];
    }

    protected function register_controls() {
        $this->start_controls_section(
            'content_section',
            [
                'label' => 'Content',
                'tab' => \Elementor\Controls_Manager::TAB_CONTENT,
            ]
        );

        $this->add_control(
            'title',
            [
                'label' => 'Title',
                'type' => \Elementor\Controls_Manager::TEXT,
                'default' => 'Title',
            ]
        );

        $this->end_controls_section();

        // Style controls
        $this->start_controls_section(
            'style_section',
            [
                'label' => 'Style',
                'tab' => \Elementor\Controls_Manager::TAB_STYLE,
            ]
        );

        $this->add_control(
            'title_color',
            [
                'label' => 'Color',
                'type' => \Elementor\Controls_Manager::COLOR,
                'selectors' => [
                    '{{WRAPPER}} .title' => 'color: {{VALUE}}',
                ],
            ]
        );

        $this->end_controls_section();
    }

    protected function render() {
        $settings = $this->get_settings_for_display();
        ?>
        <div class="custom-widget">
            <h2 class="title"><?php echo esc_html($settings['title']); ?></h2>
        </div>
        <?php
    }
}
```

## Registar Widget

```php
// functions.php ou plugin
add_action('elementor/widgets/register', function($widgets_manager) {
    require_once(__DIR__ . '/widgets/custom-widget.php');
    $widgets_manager->register(new \Custom_Widget());
});
```

## Theme Builder

### Header

```
Site Logo | Navigation Menu | Search | Cart Icon
Sticky: Yes | Transparent: Optional
```

### Footer

```
4 Columns: About | Links | Contact | Social
Copyright row
```

### Single Post

```
Featured Image
Title + Meta (Author, Date, Categories)
Content
Author Box
Related Posts
```

### Archive

```
Title
Filters (JetSmartFilters)
Post Grid/List (JetEngine)
Pagination
```

## Crocoblock Plugins

| Plugin | Uso Principal |
|--------|---------------|
| **JetEngine** | CPT, Meta Fields, Dynamic Content, Listings |
| **JetElements** | Widgets adicionais (Timeline, Progress Bar) |
| **JetSmartFilters** | Filtros AJAX para listings |
| **JetWooBuilder** | Templates WooCommerce avançados |
| **JetPopup** | Popups com triggers avançados |
| **JetTabs** | Tabs, Accordions, Toggle |
| **JetFormBuilder** | Forms com lógica condicional |

## JetEngine - Custom Post Type

```php
// Via código (alternativa ao JetEngine UI)
add_action('init', function() {
    register_post_type('portfolio', [
        'labels' => [
            'name' => 'Portfolio',
            'singular_name' => 'Project'
        ],
        'public' => true,
        'has_archive' => true,
        'supports' => ['title', 'editor', 'thumbnail'],
        'show_in_rest' => true,
    ]);
});

// Meta boxes via JetEngine UI recomendado
```

## Performance Tips

### 1. Lazy Load

```php
// Activar lazy load para imagens
add_filter('wp_lazy_loading_enabled', '__return_true');
```

### 2. Desactivar Google Fonts (se usar fonts locais)

```php
add_filter('elementor/frontend/print_google_fonts', '__return_false');
```

### 3. Limitar revisões

```php
// wp-config.php
define('WP_POST_REVISIONS', 3);
```

### 4. Usar Flexbox Container

```
Preferir: Flexbox Container (moderno)
Evitar: Section > Column (legacy, mais pesado)
```

### 5. Minimizar Widgets

```
Regra: Máximo 50 widgets por página
Usar: CSS custom em vez de widgets simples
```

## Breakpoints

```
Desktop: > 1024px
Tablet: 768-1024px
Mobile: < 768px

Configuração:
Elementor > Settings > Advanced > Breakpoints
```

## Troubleshooting

### Widget não aparece / CSS desactualizado

```bash
# CWP — SEMPRE com prefixo PHP completo
PHP="/opt/alt/php-fpm83/usr/bin/php"
WP="$PHP /usr/local/bin/wp --allow-root --path=/home/USER/public_html"

# Regenerar CSS (após qualquer alteração programática)
$WP elementor flush-css --regenerate

# Substituição segura de URLs (NUNCA usar wp search-replace directamente)
$WP elementor replace-urls https://antigo.com https://novo.com

# Sincronizar BD após update do plugin
$WP elementor update db
```

### Erro após update

```bash
# Rollback Elementor
Elementor > Tools > Version Control > Rollback
```

### Performance lenta

```
1. Desactivar Google Fonts desnecessárias
2. Activar cache CSS minificado
3. Usar Flexbox Container
4. Lazy load imagens
5. Limitar widgets por página
```

## Automação Programática (WP-CLI / MySQL / REST API)

Para deploy automatizado, pipelines IA, migração em massa e manipulação programática do Elementor sem GUI, consultar:

**`references/automation.md`** — Referência completa com:
- Pipeline de deploy CWP (kit import + replace-urls + flush-css)
- Estrutura `_elementor_data` JSON e queries MySQL com `JSON_REPLACE`
- REST API custom endpoint (com `wp_slash`, cache invalidation)
- PHP Dynamic Tags para conteúdo runtime (requer Pro)
- Geração de Kit ZIP em Python
- Rebranding global via `elementor_active_kit`
- Regras críticas (NUNCA `wp search-replace` em `_elementor_data`)
- MCP Elementor (Ultimate Elementor MCP, ~60 tools)

## Datasets Dify

| Dataset | ID | Prioridade |
|---------|----|-----------:|
| **Elementor** | `9c77d3e2-4d88-4a43-abff-d4e681267cc7` | 1 |
| **Crocoblock** | `bdf85c26-1824-4021-92d1-be20501b35ac` | 1 |
| **Crocooblock** | `139cdf67-afce-46ec-9ccd-2a06040e5b9d` | 1 |
| **Wordpress** | `9da0b2b9-5051-4b99-b9f6-20bf35067092` | 2 |

---

## Referências Adicionais

- **`references/automation.md`** — Automação programática completa (WP-CLI pipelines, MySQL, REST API, PHP Hooks, Kits, CSS)

---

**Versão**: 1.2.0 | **Autor**: Descomplicar® | **Actualizado**: 18-02-2026