---
name: wordpress-elementor
description: Tool-usage playbook for driving Elementor correctly through this plugin's elementor_* tools — page/element model, safe edit order, global kit, templates, and the gotchas that corrupt _elementor_data. Read before any non-trivial Elementor build or edit.
version: 1.0.0
auto-load: false
tags: [elementor, wordpress, tools, workflow]
---

# WordPress + Elementor — Tool Playbook

## When to use this skill

Load before any Elementor build or edit that is more than a one-line text change. `landing-page-builder` tells you *what* page to build; this tells you *how* to drive the tools without corrupting the document.

---

## The Elementor data model (what you're actually editing)

An Elementor page is a tree stored in post meta `_elementor_data` as JSON. Nodes are **containers/sections → columns → widgets**. Every node has an `id` and a `settings` object. The plugin's tools read and write this tree for you — never hand-edit the raw JSON through `update_post_meta` unless there is no tool for the change, because a malformed tree blanks the page in the editor.

Each widget type has its own settings schema. Discover it, don't guess:

- `elementor_list_widgets` — what widget types exist on this install (Pro/Woodmart add more).
- `elementor_get_page` / `elementor_get_element` — read the current tree and a node's exact settings before editing it.
- `elementor_get_page_outline` — a compact structural view for planning edits.

---

## Safe build order

1. `elementor_create_page` → title, status `draft`.
2. Per section, outer wrapper first: `elementor_add_container` (or `elementor_add_section`).
3. Set the container background and padding before adding children.
4. Inner content wrapper: another `elementor_add_container` (max-width, centered).
5. Add widgets into the inner wrapper: `elementor_add_heading`, `elementor_add_text`, `elementor_add_button`, `elementor_add_image`, or the generic `elementor_add_widget` for anything else.
6. Only after a section is complete, move to the next. Building depth-first per section keeps parent IDs straight.

Each add returns the new element's `id`. Hold onto it — later edits, motion, and nesting all key off that id.

---

## Safe edit order

- Read before you write: `elementor_get_element` to see current settings, merge your change, then `elementor_update_element` / `elementor_update_widget`. Blind writes drop sibling settings.
- Structural moves use the dedicated tools — `elementor_move_element`, `elementor_reorder_elements`, `elementor_duplicate_element`, `elementor_remove_element` — not hand-rebuilt JSON.
- Bulk changes: `elementor_batch_update` for many edits in one pass; `elementor_replace_text` / `elementor_replace_urls` for find-and-replace across the page.
- **Always finish with `elementor_regenerate_css`** (or `elementor_flush_css`), then `cache_purge_all`. Elementor serves a per-page CSS file; without regeneration your changes render in the editor but not on the live page.

---

## The global kit — consistency lives here

Don't style widgets one by one when a global setting exists.

- Colors: `elementor_get_global_colors`, `elementor_set_global_color`.
- Fonts: `elementor_get_global_fonts`, `elementor_set_global_font`.
- Kit settings (site-wide spacing, buttons, defaults): `elementor_list_kits`, `elementor_get_kit_settings`, `elementor_update_kit_settings`, `elementor_get_kit_custom_css`, `elementor_update_kit_custom_css`.
- Page-level CSS when you truly need it: `elementor_get_page_custom_css`, `elementor_update_page_custom_css`.

Set the system once, reference it everywhere. A hex pasted into a widget is a future inconsistency.

---

## Templates, conditions, dynamic content

- Save a built section for reuse: `elementor_save_as_template`; apply it elsewhere: `elementor_apply_template`; browse: `elementor_list_templates` / `elementor_list_library`, import/export with `elementor_import_template` / `elementor_export_page`.
- Theme-builder display rules (where a header/footer/template shows): `elementor_get_conditions`.
- Dynamic tags (Pro — pull post/ACF/site data into widgets): `elementor_get_dynamic_tags`.
- Form submissions (Pro forms): `elementor_get_form_submissions`.
- Clone a whole page: `elementor_clone_page` / `duplicate_elementor_page`.

---

## Woodmart + Elementor

This site runs Woodmart. Confirm theme widget support before relying on it: `theme_elementor_support`, `theme_elementor_tokens`, `theme_woodmart_elements`. Woodmart registers its own Elementor widgets — `elementor_list_widgets` will show them. For Woodmart theme options and HTML blocks, use the `woodmart-mcp` skill's tools, not Elementor's.

---

## Gotchas that cost hours

- **Forgot `elementor_regenerate_css`** → "my change isn't showing". Regenerate, then purge cache.
- **Edited a widget without reading it first** → lost other settings on that widget. Always get → merge → update.
- **Hand-wrote `_elementor_data`** → editor shows a blank/broken page. Use the element tools.
- **Duplicate slug `-2`** after re-running a build → check and fix the slug before publishing.
- **Mobile untouched** → set responsive padding/typography per container; desktop values suffocate on phones.
- **Published while cache served the old page** → `cache_detect` to see the engine, `cache_purge_all` after every structural change.