diff --git a/skills/wordpress-elementor.md b/skills/wordpress-elementor.md new file mode 100644 index 0000000..becf5cb --- /dev/null +++ b/skills/wordpress-elementor.md @@ -0,0 +1,87 @@ +--- +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.