Elementor V4 atomic widget development patterns for Vikingo plugins. MUST be applied when creating or modifying Elementor widgets, dynamic tags, or editor previews in any Vikingo WordPress plugin — the atomic API (Elementor\Modules\AtomicWidgets) is undocumented and internal, so this skill captures the proven guard patterns (class_exists + experiment check + try/catch), the widget anatomy (define_props_schema, define_atomic_controls, get_atomic_settings computing rendered_html server-side), the Twig template contract, the REST-based live editor preview hydration, prop/control type reference, the post-Elementor-update checklist, and known pitfalls. Triggers on Elementor widget, atomic widget, Atomic_Widget_Base, twig template, dynamic tag, editor preview, e_atomic_elements, Elementor V4, or any vk- plugin Elementor integration.
A V4 atomic API (Elementor\Modules\AtomicWidgets\*) BELSŐ, nem dokumentált és
experiment mögött él. Ez a skill a három élesben bizonyított Vikingo
implementáció (vk-tematika, vk-ajanlas, vikingo-bunny-video) desztillált
tudása. Az itteni minták kötelezők minden új Vikingo atomic widgetnél.
0. Alapelvek
Minden Elementor-érintés guard mögött. Ha az API változik vagy hiányzik,
a widget csendben nem regisztrálódik; az oldal nem törhet el.
Mindig van shortcode-tartalék. A render logika Elementor-független
osztályban él (Frontend/Renderer minta), a widget és a shortcode ugyanazt
hívja. Elementor nélkül is mindennek működnie kell.
A HTML szerveroldalon készül. A twig sablon csak beilleszti a kész
rendered_html-t; a szerkesztői vászonra REST-hidratálás hozza az élő képet.
A referencia-repók verzióját Elementor-frissítéskor cserélni kell, és utána a
9. pont ellenőrzőlistáját végigfutni. (Utolsó ismert állapot: Elementor 4.3.2,
Pro 4.3.0 - 2026-09-26. A platform repo docs/elementor*/ mappája - gitignore-olt -
ugyanezt a verziót tartja; frissítéskor a kettő együtt cserélendő.)
2. Regisztráció és guardok
A belépési pont egy Elementor/Module osztály, amit a Plugin csak akkor hív,
ha egyáltalán van Elementor. A minta:
public static function register(): void {
// Atomic widgetek: csak ha a V4 atomic alaposztály elérhető.
if ( class_exists( \Elementor\Modules\AtomicWidgets\Elements\Base\Atomic_Widget_Base::class ) ) {
add_filter(
'elementor/widgets/register',
static function ( $widgets_manager ) {
$widgets_manager->register( new Widgets\SajatWidget() );
return $widgets_manager;
}
);
}
}
Szigorúbb környezetben (ha klasszikus fallback widget is van, mint a bunny-nál)
a teljes ellenőrzés: minden HASZNÁLT osztályra class_exists (alaposztály,
minden control, minden prop type), PLUSZ az experiment:
és a $widgets_manager->register() hívás try/catch (\Throwable) blokkban,
hogy egy Elementor-frissítés okozta törés soha ne legyen fatal, csak fallback.
A kimaradás nem lehet csendes. A try/catch és az Elementor saját
sablon-renderelője is elnyeli a hibát, élesen gyakran PHP-napló sincs, így a
widget helyén egyszerűen üres hely marad minden oldalon. A bevált minta
(vk-vikingo-hu-platform 0.58.8, Kernel\Elementor\Registrar + Allapot):
minden widget EGY közös regisztrálón megy (widget-gyárakkal), amely a hibákat
összegyűjti; a elementor/widgets/registerPHP_INT_MAX prioritásán az
eredmény optionbe kerül (csak változáskor írva). Az Elementor / Pro / bővítmény
verzió-ujjlenyomatának változásakor egy WP-Cron feladat minden widgetet
alapbeállítással példányosít és lerenderel (create_element_instance +
print_element); az üres vagy kivételt dobó widget hiba. Hibánál tartós
admin-értesítés „Ellenőrzés újra” gombbal.
3. A widget anatómiája
class SajatWidget extends Atomic_Widget_Base {
use Has_Template;
// Saját újradeklarálás, különben a közös ős STATIKUS property-jét írnánk,
// és két Vikingo widget egymás leírását mutatná.
public static $widget_description = null;
public function __construct( $data = array(), $args = null ) {
static::$widget_description = __( 'Leírás…', 'vk-plugin' );
parent::__construct( $data, $args );
}
public static function get_element_type(): string {
return 'vk-sajat'; // ez kerül az Elementor oldal-JSON-ba: SOHA nem változhat!
}
protected static function define_props_schema(): array { /* STATIKUS! */ }
protected function define_atomic_controls(): array { /* Section-ök */ }
public function get_atomic_settings(): array {
$settings = parent::get_atomic_settings();
// A HTML-t ITT számoljuk szerveroldalon; a mellékhatások (asset enqueue,
// JSON-LD regisztráció) is itt indulnak, mert a twig-ben már késő.
$settings['rendered_html'] = $this->render_html( $settings );
return $settings;
}
protected function get_templates(): array {
return array( 'vikingo/sajat' => VK_X_PATH . 'assets/twig/sajat.html.twig' );
}
}
Kritikus tudnivalók:
get_element_type() értéke bekerül minden Elementor oldal adatai közé.
Átnevezése az összes meglévő oldalon eltünteti a widgetet. Refaktornál,
plugin-összevonásnál a widget-név VÁLTOZATLAN marad.
define_props_schema() statikus, ezért a közös prop-készletet is statikus
metódusban add tovább (common_props_schema() minta az ajanlas
AbstractTestimonialWidget-jében).
A classes prop kötelező eleme a sémának:
'classes' => Classes_Prop_Type::make()->default( array() ).
A Has_Template::render() a kivételeket lenyeli (csak ELEMENTOR_DEBUG
mellett dobja tovább) — némán üres widget = valószínűleg twig- vagy
kontextushiba, debug módban derül ki.
4. Prop típusok és controlok (a használt készlet)
Prop type (PropTypes\…)
Control (Controls\Types\…)
Megjegyzés
Primitives\String_Prop_Type
Text_Control, Textarea_Control, Select_Control
->enum([...]) a select értékkészletéhez
Primitives\Boolean_Prop_Type
Switch_Control
Primitives\Number_Prop_Type
Number_Control
Image_Prop_Type
Image_Control
médiatár-választó
Link_Prop_Type
Link_Control
Classes_Prop_Type
–
kötelező, az Elementor kezeli
Minden propnak legyen leírása (->description( __( '…' ) ), Elementor
4.2-ben is létező metódus; a 4.3-tól az Elementor MCP / LLM-séma ebből
dolgozik). Mit csinál, milyen értéket vár (slug, ID, URL), mit jelent az
üres vagy a 0; enum nélküli választónál az érvényes értékek is. Ciklusban
készülő propoknál a leírás a címke-listából épüljön (sprintf).
A controlok Section::make()->set_label()->set_id()->set_items([...])
szekciókba rendezve mennek, Xxx_Control::bind_to( 'prop_nev' ) kötéssel.
Dinamikus tartalom-választáshoz (pl. CPT bejegyzések) létezik Query_Control
(set_query_config()), de a bevált Vikingo minta az egyszerű
Select_Control + saját options-forrás (lásd tematika CourseOptions).
5. A twig sablon szerződése
A Has_Template::render() kontextusa: id, interaction_id, type,
settings, tag (4.3-tól), base_styles. A tag a
get_computed_html_tag( $settings ) eredménye: ha a sémában core-alakú link
prop van élő href-fel, a; ha tag prop van, annak értéke; különben div.
A Vikingo sablonok a tag-et nem használják (a gyökér mindig div). A Vikingo sablon-minta:
{% set classes = settings.classes | default([]) | join(' ') %}
<div data-id="{{ id }}" data-e-type="{{ type }}" class="{{ classes }}"
data-vk-course="{{ settings.course }}">
{% if settings.rendered_html is defined and settings.rendered_html %}
{{ settings.rendered_html | raw }}
{% else %}
<div style="border:1px dashed #FF544D;…">Vikingo X – előnézet betöltése…</div>
{% endif %}
</div>
A sablon CSAK beilleszt (| raw), logika nincs benne.
Minden beállítás, amit az előnézetnek látnia kell, data-vk-* attribútumként
is kikerül — ebből dolgozik a hidratáló JS.
A helyettesítő doboz azért kell, mert a szerkesztőben a twig KLIENS oldalon
fut, ahol a rendered_html nem létezik.
6. Szerkesztői élő előnézet (REST-hidratálás)
A szerkesztő vásznán a twig kliens oldalon fut, a szerveroldali
rendered_html ott nem érhető el. A bevált megoldás három elem:
REST végpont (vikingo/v1/{plugin}/render, GET, publikus — ugyanazt a
HTML-t adja, ami a frontenden is megjelenik): a paraméterekből lerendereli
a widgetet és { html: … }-t ad vissza.
Preview enqueue: az elementor/preview/enqueue_styles és
…/enqueue_scripts hookon betöltjük a frontend CSS/JS-t és az
editor-preview.js-t, wp_add_inline_script-tel átadva a REST URL-t.
editor-preview.js: MutationObserver figyeli a vásznat (250 ms
debounce), a [data-e-type="vk-…"] elemeket a data-vk-* attribútumokból
épített query-vel hidratálja. A lekért query-t data-vk-hydrated-ben
tárolja, így változatlan beállításnál nincs újabb fetch. Hidratálás után
meghívja a frontend init függvényt (window.vkXInit), hogy az interakciók
a vásznon is éljenek.
Teljes referencia: tematika assets/js/editor-preview.js +
src/Rest/RenderController.php + src/Elementor/Module.php.
7. Dynamic tag (stabil API, nem atomic)
A dynamic tag a RÉGI, dokumentált API-ra épül (Elementor\Core\DynamicTags\Tag),
guard: class_exists( \Elementor\Core\DynamicTags\Tag::class ), regisztráció az
elementor/dynamic_tags/register hookon. A tag alap az ingyenes Elementorban
van, a beszúró felület a Pro-ban. Controlok a klasszikus
Controls_Manager::SELECT stílusban. Minta: tematika TematikaAdatTag.
8. CSS az Elementor kit ellen
Az Elementor kit globális button/h2/p stílusai felülírják a widget CSS-ét.
Vikingo szabály: minden szabály a widget gyökérosztályával prefixelve
(.vk-x .vk-x-gomb — dupla osztály-specificitás) és explicit resetekkel.
Tokenek: --vkx-* lokális változók var(--vk-*, fallback) értékkel, hogy az
oldal design systeme felülbírálhasson. JSON-LD SOHA nem a widget kimenetébe
megy, hanem wp_footer-be, mert az Elementor content pipeline megrongálhatja.
9. Elementor-frissítés utáni ellenőrzőlista
Frissítéskor a referencia-repókat lecserélni, majd ellenőrizni:
Atomic_Widget_Base és Has_Template létezik-e még ugyanazon a néven
(elements/base/), változott-e a konstruktor vagy az absztrakt metódusok.
Pillanatkép előtte / utána a klónon (vk-vikingo-hu-platform
docs/widget-pillanatkep/): cím, séma, vezérlők, config és
alapbeállítású kimenet – az elvárt eredmény 0 eltérés.
Élesen az állapotfigyelő próbája (admin-értesítés nincs, vagy
„Ellenőrzés újra” után „mind a N widget rendben”).
9.1. Beágyazott (gyerekes) elem
Ha a tartalom maga az Elementor-adat (kézzel kitöltött diák, kártyák), nem
widget kell, hanem az Elementor Accordion / Tabs mintájú beágyazott elem.
Bizonyított minta: vk-vikingo-hu-platform 0.61.0, src/Korhinta/
(Tartalomkörhinta). Ez a 0. pont két elve alóli SZÁNDÉKOS kivétel: nincs
rendered_html és nincs shortcode-tartalék, mert Elementor nélkül nincs
tartalom.
Anatómia:Atomic_Element_Base + use Has_Element_Template; a twig
gyökerében <!-- elementor-children-placeholder -->. A szülő
define_allowed_child_types() + define_default_children()
(Element_Builder::make( TIPUS )->children(...)->build()), a gyerek
should_show_in_panel() = false. A gyerek a szülő adatát
define_render_context() → Render_Context::get( Szulo::class ) útján
kapja (pl. a saját sorszámát).
Assetek:get_style_depends() / get_script_depends() a
frontenden működik; a frontend-kezelő
window.elementorV2.frontendHandlers.register({ elementType, id, callback({ element, signal }) }), függőség:
elementor-v2-frontend-handlers. A vásznon is lefut.
A helyőrző a gyökér KÖZVETLEN gyereke legyen a vásznon (a szerkesztő
a gyökér childNodes-ai közt keresi). Ha a frontenden más szerkezet kell
(szalag, gombok), a twig ága: {% if editor_attributes is defined %} =
vászon. A PHP-oldali str_replace a helyőrzőt bárhol megtalálja.
A szülőt az Elementor nem korlátozza: a gyerek kihúzható a szülőből,
és a szülőbe bármi behúzható. Szerkesztő-szkript (elementor/editor/ after_enqueue_scripts) $e.modules.hookData.Dependency horgokkal a
document/elements/move, /create, /paste parancsokon. A
permanently_locked meta NEM megoldás: a duplikálást, másolást és
törlést is tiltja.
A kezdő gyerekek styles kulcsát az Elementor eldobja (az osztály
megmarad, a stílus nem). Globális osztály (címkéből feloldva: a kit
_elementor_global_classes_labels metája) működik; színt a saját CSS adjon
(0,1,2) erősséggel: a kit hN-jénél (0,1,1) erősebb, a helyi stílusnál
és a globális osztálynál (.elementor .x = 0,2,0) gyengébb.
A vásznon minden widget .elementor-element burkolóban ül: a >
gyerek-szelektorok e szintet is fedjék le.
Generikus REST-hidratáló (ha van): a beágyazott elemet hagyja ki
(jelölő attribútum), különben a gyerekeket felülírja.
10. Ismert buktatók
Widget-név = adat.get_element_type() átnevezése minden meglévő
oldalról törli a widgetet. Összevonásnál, átnevezésnél tilos hozzányúlni.
$widget_description statikus és közös — minden widgetben újra kell
deklarálni, különben az utoljára konstruált widget leírása jelenik meg
mindenhol.
A define_props_schema() statikus, nem fér hozzá $this-hez; a
dinamikus alapértékek (pl. fordított stringek) mehetnek bele, de
példány-állapot nem.
Mellékhatások helye a get_atomic_settings() (asset enqueue, schema):
a render()-t a Has_Template adja, oda nem nyúlunk bele.
A szerkesztői vászon nem futtat PHP-t — bármi, ami a frontenden PHP-ból
jön, a vásznon csak REST-hidratálással jelenik meg.
Üres widget a frontenden, hiba nélkül: a Has_Template::render()
try/catch-e nyelte le — ELEMENTOR_DEBUG mellett újratesztelni.
link / tag nevű prop (4.3-tól): a core Html_Tag_Computer ezekből
számolja a tag kontextus-kulcsot és a szerkesztői default_html_tag-et. A
string típusú link prop ártalmatlan (csak tömb alakú, href-es link billent
a-ra), de új widgetben ne adj ilyen nevet core-tól eltérő jelentéssel.
Default Styles (4.3-tól): az Elementor globális HTML-tag stílusai
.e-default-{tag} osztályon át hatnak, amit csak a core sablonok
_macros.html.twig-je rak ki. A rendered_html-t beillesztő Vikingo
widgeteket NEM érintik - ez szándékos, a widget saját CSS-e dönt.
Elementor MCP (4.3-tól): minden prop típus to_json_schema()-t kapott,
így a V4 widgetjeink az MCP-ben szerkeszthető elemként látszanak (a V3-at az
MCP elutasítja). Saját prop típust ezért a core ősből származtass, hogy a
JSON-sémája öröklődjön.
A Has_Template::render() csak \Exception-t nyel le, \Error-t nem
(Elementor 4.3.2): egy TypeError vagy hívás nem létező metódusra a
get_atomic_settings()-ben a látogatónál végzetes hiba. A renderelő kód
típusai legyenek szigorúan kezelve, és a próba (\Throwable) ezt is elkapja.
File:// alapú headless Chrome teszt megbízhatatlan — vizuális
ellenőrzéshez mindig php -S szerver + Playwright (channel: chrome).
1---2name: vikingo-elementor-atomic3description: Elementor V4 atomic widget development patterns for Vikingo plugins. MUST be applied when creating or modifying Elementor widgets, dynamic tags, or editor previews in any Vikingo WordPress plugin — the atomic API (Elementor\Modules\AtomicWidgets) is undocumented and internal, so this skill captures the proven guard patterns (class_exists + experiment check + try/catch), the widget anatomy (define_props_schema, define_atomic_controls, get_atomic_settings computing rendered_html server-side), the Twig template contract, the REST-based live editor preview hydration, prop/control type reference, the post-Elementor-update checklist, and known pitfalls. Triggers on Elementor widget, atomic widget, Atomic_Widget_Base, twig template, dynamic tag, editor preview, e_atomic_elements, Elementor V4, or any vk- plugin Elementor integration.4metadata:5 source: https://skillmd.com/skills/vikingokft/vikingo-elementor-atomic6---78# Vikingo – Elementor V4 atomic widget minták910A V4 atomic API (`Elementor\Modules\AtomicWidgets\*`) BELSŐ, nem dokumentált és11experiment mögött él. Ez a skill a három élesben bizonyított Vikingo12implementáció (vk-tematika, vk-ajanlas, vikingo-bunny-video) desztillált13tudása. Az itteni minták kötelezők minden új Vikingo atomic widgetnél.1415## 0. Alapelvek1617- **Minden Elementor-érintés guard mögött.** Ha az API változik vagy hiányzik,18 a widget csendben nem regisztrálódik; az oldal nem törhet el.19- **Mindig van shortcode-tartalék.** A render logika Elementor-független20 osztályban él (`Frontend/Renderer` minta), a widget és a shortcode ugyanazt21 hívja. Elementor nélkül is mindennek működnie kell.22- **A HTML szerveroldalon készül.** A twig sablon csak beilleszti a kész23 `rendered_html`-t; a szerkesztői vászonra REST-hidratálás hozza az élő képet.2425## 1. Referencia-források (helyi gépen)2627| Mi | Hol |28|---|---|29| Elementor teljes forrás | `~/Documents/Github/reference-elementor/` |30| Elementor Pro teljes forrás | `~/Documents/Github/reference-elementor-pro/` |31| Atomic alaposztály | `reference-elementor/modules/atomic-widgets/elements/base/atomic-widget-base.php` |32| Has_Template trait (render + twig kontextus) | `.../elements/base/has-template.php` |33| Core minta-widget | `reference-elementor/modules/atomic-widgets/elements/atomic-youtube/` |34| Control típusok | `reference-elementor/modules/atomic-widgets/controls/types/` |35| Prop típusok | `reference-elementor/modules/atomic-widgets/prop-types/` |36| Működő Vikingo minták | `wp-plugin-vikingo-hu-tematika/src/Elementor/`, `wp-plugin-vikingo-ajanlas/src/Elementor/` |3738A referencia-repók verzióját Elementor-frissítéskor cserélni kell, és utána a399. pont ellenőrzőlistáját végigfutni. (Utolsó ismert állapot: Elementor 4.3.2,40Pro 4.3.0 - 2026-09-26. A platform repo `docs/elementor*/` mappája - gitignore-olt -41ugyanezt a verziót tartja; frissítéskor a kettő együtt cserélendő.)4243## 2. Regisztráció és guardok4445A belépési pont egy `Elementor/Module` osztály, amit a Plugin csak akkor hív,46ha egyáltalán van Elementor. A minta:4748```php49public static function register(): void {50 // Atomic widgetek: csak ha a V4 atomic alaposztály elérhető.51 if ( class_exists( \Elementor\Modules\AtomicWidgets\Elements\Base\Atomic_Widget_Base::class ) ) {52 add_filter(53 'elementor/widgets/register',54 static function ( $widgets_manager ) {55 $widgets_manager->register( new Widgets\SajatWidget() );56 return $widgets_manager;57 }58 );59 }60}61```6263Szigorúbb környezetben (ha klasszikus fallback widget is van, mint a bunny-nál)64a teljes ellenőrzés: minden HASZNÁLT osztályra `class_exists` (alaposztály,65minden control, minden prop type), PLUSZ az experiment:6667```php68$experiments = \Elementor\Plugin::$instance->experiments;69$atomic_ok = $experiments && $experiments->is_feature_active( 'e_atomic_elements' );70```7172és a `$widgets_manager->register()` hívás `try/catch (\Throwable)` blokkban,73hogy egy Elementor-frissítés okozta törés soha ne legyen fatal, csak fallback.7475**A kimaradás nem lehet csendes.** A try/catch és az Elementor saját76sablon-renderelője is elnyeli a hibát, élesen gyakran PHP-napló sincs, így a77widget helyén egyszerűen üres hely marad minden oldalon. A bevált minta78(vk-vikingo-hu-platform 0.58.8, `Kernel\Elementor\Registrar` + `Allapot`):79minden widget EGY közös regisztrálón megy (widget-gyárakkal), amely a hibákat80összegyűjti; a `elementor/widgets/register` `PHP_INT_MAX` prioritásán az81eredmény optionbe kerül (csak változáskor írva). Az Elementor / Pro / bővítmény82verzió-ujjlenyomatának változásakor egy WP-Cron feladat minden widgetet83alapbeállítással példányosít és lerenderel (`create_element_instance` +84`print_element`); az üres vagy kivételt dobó widget hiba. Hibánál tartós85admin-értesítés „Ellenőrzés újra” gombbal.8687## 3. A widget anatómiája8889```php90class SajatWidget extends Atomic_Widget_Base {91 use Has_Template;9293 // Saját újradeklarálás, különben a közös ős STATIKUS property-jét írnánk,94 // és két Vikingo widget egymás leírását mutatná.95 public static $widget_description = null;9697 public function __construct( $data = array(), $args = null ) {98 static::$widget_description = __( 'Leírás…', 'vk-plugin' );99 parent::__construct( $data, $args );100 }101102 public static function get_element_type(): string {103 return 'vk-sajat'; // ez kerül az Elementor oldal-JSON-ba: SOHA nem változhat!104 }105106 protected static function define_props_schema(): array { /* STATIKUS! */ }107 protected function define_atomic_controls(): array { /* Section-ök */ }108109 public function get_atomic_settings(): array {110 $settings = parent::get_atomic_settings();111 // A HTML-t ITT számoljuk szerveroldalon; a mellékhatások (asset enqueue,112 // JSON-LD regisztráció) is itt indulnak, mert a twig-ben már késő.113 $settings['rendered_html'] = $this->render_html( $settings );114 return $settings;115 }116117 protected function get_templates(): array {118 return array( 'vikingo/sajat' => VK_X_PATH . 'assets/twig/sajat.html.twig' );119 }120}121```122123Kritikus tudnivalók:124125- **`get_element_type()` értéke bekerül minden Elementor oldal adatai közé.**126 Átnevezése az összes meglévő oldalon eltünteti a widgetet. Refaktornál,127 plugin-összevonásnál a widget-név VÁLTOZATLAN marad.128- **`define_props_schema()` statikus**, ezért a közös prop-készletet is statikus129 metódusban add tovább (`common_props_schema()` minta az ajanlas130 `AbstractTestimonialWidget`-jében).131- A `classes` prop kötelező eleme a sémának:132 `'classes' => Classes_Prop_Type::make()->default( array() )`.133- A `Has_Template::render()` a kivételeket lenyeli (csak `ELEMENTOR_DEBUG`134 mellett dobja tovább) — némán üres widget = valószínűleg twig- vagy135 kontextushiba, debug módban derül ki.136137## 4. Prop típusok és controlok (a használt készlet)138139| Prop type (`PropTypes\…`) | Control (`Controls\Types\…`) | Megjegyzés |140|---|---|---|141| `Primitives\String_Prop_Type` | `Text_Control`, `Textarea_Control`, `Select_Control` | `->enum([...])` a select értékkészletéhez |142| `Primitives\Boolean_Prop_Type` | `Switch_Control` | |143| `Primitives\Number_Prop_Type` | `Number_Control` | |144| `Image_Prop_Type` | `Image_Control` | médiatár-választó |145| `Link_Prop_Type` | `Link_Control` | |146| `Classes_Prop_Type` | – | kötelező, az Elementor kezeli |147148- **Minden propnak legyen leírása** (`->description( __( '…' ) )`, Elementor149 4.2-ben is létező metódus; a 4.3-tól az Elementor MCP / LLM-séma ebből150 dolgozik). Mit csinál, milyen értéket vár (slug, ID, URL), mit jelent az151 üres vagy a 0; enum nélküli választónál az érvényes értékek is. Ciklusban152 készülő propoknál a leírás a címke-listából épüljön (sprintf).153- `Select_Control::set_options()` formátuma:154 `array( array( 'value' => 'x', 'label' => 'X' ), … )` — NEM kulcs=>érték!155- A controlok `Section::make()->set_label()->set_id()->set_items([...])`156 szekciókba rendezve mennek, `Xxx_Control::bind_to( 'prop_nev' )` kötéssel.157- Dinamikus tartalom-választáshoz (pl. CPT bejegyzések) létezik `Query_Control`158 (`set_query_config()`), de a bevált Vikingo minta az egyszerű159 `Select_Control` + saját options-forrás (lásd tematika `CourseOptions`).160161## 5. A twig sablon szerződése162163A `Has_Template::render()` kontextusa: `id`, `interaction_id`, `type`,164`settings`, `tag` (4.3-tól), `base_styles`. A `tag` a165`get_computed_html_tag( $settings )` eredménye: ha a sémában core-alakú `link`166prop van élő href-fel, `a`; ha `tag` prop van, annak értéke; különben `div`.167A Vikingo sablonok a `tag`-et nem használják (a gyökér mindig `div`). A Vikingo sablon-minta:168169```twig170{% set classes = settings.classes | default([]) | join(' ') %}171<div data-id="{{ id }}" data-e-type="{{ type }}" class="{{ classes }}"172 data-vk-course="{{ settings.course }}">173{% if settings.rendered_html is defined and settings.rendered_html %}174{{ settings.rendered_html | raw }}175{% else %}176<div style="border:1px dashed #FF544D;…">Vikingo X – előnézet betöltése…</div>177{% endif %}178</div>179```180181- A sablon CSAK beilleszt (`| raw`), logika nincs benne.182- Minden beállítás, amit az előnézetnek látnia kell, `data-vk-*` attribútumként183 is kikerül — ebből dolgozik a hidratáló JS.184- A helyettesítő doboz azért kell, mert a szerkesztőben a twig KLIENS oldalon185 fut, ahol a `rendered_html` nem létezik.186187## 6. Szerkesztői élő előnézet (REST-hidratálás)188189A szerkesztő vásznán a twig kliens oldalon fut, a szerveroldali190`rendered_html` ott nem érhető el. A bevált megoldás három elem:1911921. **REST végpont** (`vikingo/v1/{plugin}/render`, GET, publikus — ugyanazt a193 HTML-t adja, ami a frontenden is megjelenik): a paraméterekből lerendereli194 a widgetet és `{ html: … }`-t ad vissza.1952. **Preview enqueue**: az `elementor/preview/enqueue_styles` és196 `…/enqueue_scripts` hookon betöltjük a frontend CSS/JS-t és az197 `editor-preview.js`-t, `wp_add_inline_script`-tel átadva a REST URL-t.1983. **editor-preview.js**: `MutationObserver` figyeli a vásznat (250 ms199 debounce), a `[data-e-type="vk-…"]` elemeket a `data-vk-*` attribútumokból200 épített query-vel hidratálja. A lekért query-t `data-vk-hydrated`-ben201 tárolja, így változatlan beállításnál nincs újabb fetch. Hidratálás után202 meghívja a frontend init függvényt (`window.vkXInit`), hogy az interakciók203 a vásznon is éljenek.204205Teljes referencia: tematika `assets/js/editor-preview.js` +206`src/Rest/RenderController.php` + `src/Elementor/Module.php`.207208## 7. Dynamic tag (stabil API, nem atomic)209210A dynamic tag a RÉGI, dokumentált API-ra épül (`Elementor\Core\DynamicTags\Tag`),211guard: `class_exists( \Elementor\Core\DynamicTags\Tag::class )`, regisztráció az212`elementor/dynamic_tags/register` hookon. A tag alap az ingyenes Elementorban213van, a beszúró felület a Pro-ban. Controlok a klasszikus214`Controls_Manager::SELECT` stílusban. Minta: tematika `TematikaAdatTag`.215216## 8. CSS az Elementor kit ellen217218Az Elementor kit globális button/h2/p stílusai felülírják a widget CSS-ét.219Vikingo szabály: minden szabály a widget gyökérosztályával prefixelve220(`.vk-x .vk-x-gomb` — dupla osztály-specificitás) és explicit resetekkel.221Tokenek: `--vkx-*` lokális változók `var(--vk-*, fallback)` értékkel, hogy az222oldal design systeme felülbírálhasson. JSON-LD SOHA nem a widget kimenetébe223megy, hanem `wp_footer`-be, mert az Elementor content pipeline megrongálhatja.224225## 9. Elementor-frissítés utáni ellenőrzőlista226227Frissítéskor a referencia-repókat lecserélni, majd ellenőrizni:228229- [ ] `Atomic_Widget_Base` és `Has_Template` létezik-e még ugyanazon a néven230 (`elements/base/`), változott-e a konstruktor vagy az absztrakt metódusok.231- [ ] A `Has_Template::render()` twig kontextus-kulcsai változatlanok-e232 (`id`, `interaction_id`, `type`, `settings`, `tag`, `base_styles`).233- [ ] A használt controlok (`Select_Control::set_options` formátum!) és prop234 típusok megvannak-e.235- [ ] Az `e_atomic_elements` experiment neve/állapota változott-e236 (`modules/atomic-widgets/module.php`, `EXPERIMENT_NAME`).237- [ ] Éles teszt: widget behúzása a szerkesztőben, beállítás-változtatás238 (hidratálás frissül-e), mentés, frontend render, shortcode render.239- [ ] `ELEMENTOR_DEBUG` bekapcsolásával nincs-e lenyelt twig-kivétel.240- [ ] Pillanatkép előtte / utána a klónon (vk-vikingo-hu-platform241 `docs/widget-pillanatkep/`): cím, séma, vezérlők, config és242 alapbeállítású kimenet – az elvárt eredmény 0 eltérés.243- [ ] Élesen az állapotfigyelő próbája (admin-értesítés nincs, vagy244 „Ellenőrzés újra” után „mind a N widget rendben”).245246## 9.1. Beágyazott (gyerekes) elem247248Ha a tartalom maga az Elementor-adat (kézzel kitöltött diák, kártyák), nem249widget kell, hanem az Elementor Accordion / Tabs mintájú beágyazott elem.250Bizonyított minta: vk-vikingo-hu-platform 0.61.0, `src/Korhinta/`251(Tartalomkörhinta). Ez a 0. pont két elve alóli SZÁNDÉKOS kivétel: nincs252`rendered_html` és nincs shortcode-tartalék, mert Elementor nélkül nincs253tartalom.254255- **Anatómia:** `Atomic_Element_Base` + `use Has_Element_Template`; a twig256 gyökerében `<!-- elementor-children-placeholder -->`. A szülő257 `define_allowed_child_types()` + `define_default_children()`258 (`Element_Builder::make( TIPUS )->children(...)->build()`), a gyerek259 `should_show_in_panel()` = false. A gyerek a szülő adatát260 `define_render_context()` → `Render_Context::get( Szulo::class )` útján261 kapja (pl. a saját sorszámát).262- **Regisztráció:** `elementor/elements/elements_registered` horog,263 `$elements_manager->register_element_type()`; guard: `class_exists`264 (`Atomic_Element_Base`, `Element_Builder`) + `trait_exists`265 (`Has_Element_Template`), try/catch. A platformon:266 `Registrar::register_elements()`.267- **Assetek:** `get_style_depends()` / `get_script_depends()` a268 frontenden működik; a frontend-kezelő269 `window.elementorV2.frontendHandlers.register({ elementType, id,270 callback({ element, signal }) })`, függőség:271 `elementor-v2-frontend-handlers`. A vásznon is lefut.272- **A helyőrző a gyökér KÖZVETLEN gyereke legyen** a vásznon (a szerkesztő273 a gyökér childNodes-ai közt keresi). Ha a frontenden más szerkezet kell274 (szalag, gombok), a twig ága: `{% if editor_attributes is defined %}` =275 vászon. A PHP-oldali str_replace a helyőrzőt bárhol megtalálja.276- **A szülőt az Elementor nem korlátozza:** a gyerek kihúzható a szülőből,277 és a szülőbe bármi behúzható. Szerkesztő-szkript (`elementor/editor/278 after_enqueue_scripts`) `$e.modules.hookData.Dependency` horgokkal a279 `document/elements/move`, `/create`, `/paste` parancsokon. A280 `permanently_locked` meta NEM megoldás: a duplikálást, másolást és281 törlést is tiltja.282- **A kezdő gyerekek `styles` kulcsát az Elementor eldobja** (az osztály283 megmarad, a stílus nem). Globális osztály (címkéből feloldva: a kit284 `_elementor_global_classes_labels` metája) működik; színt a saját CSS adjon285 (0,1,2) erősséggel: a kit `hN`-jénél (0,1,1) erősebb, a helyi stílusnál286 és a globális osztálynál (`.elementor .x` = 0,2,0) gyengébb.287- **A vásznon minden widget `.elementor-element` burkolóban ül:** a `>`288 gyerek-szelektorok e szintet is fedjék le.289- **Generikus REST-hidratáló** (ha van): a beágyazott elemet hagyja ki290 (jelölő attribútum), különben a gyerekeket felülírja.291292## 10. Ismert buktatók293294- **Widget-név = adat.** `get_element_type()` átnevezése minden meglévő295 oldalról törli a widgetet. Összevonásnál, átnevezésnél tilos hozzányúlni.296- **`$widget_description` statikus és közös** — minden widgetben újra kell297 deklarálni, különben az utoljára konstruált widget leírása jelenik meg298 mindenhol.299- **A `define_props_schema()` statikus**, nem fér hozzá `$this`-hez; a300 dinamikus alapértékek (pl. fordított stringek) mehetnek bele, de301 példány-állapot nem.302- **Mellékhatások helye a `get_atomic_settings()`** (asset enqueue, schema):303 a `render()`-t a `Has_Template` adja, oda nem nyúlunk bele.304- **A szerkesztői vászon nem futtat PHP-t** — bármi, ami a frontenden PHP-ból305 jön, a vásznon csak REST-hidratálással jelenik meg.306- **Üres widget a frontenden, hiba nélkül**: a `Has_Template::render()`307 try/catch-e nyelte le — `ELEMENTOR_DEBUG` mellett újratesztelni.308- **`link` / `tag` nevű prop (4.3-tól)**: a core `Html_Tag_Computer` ezekből309 számolja a `tag` kontextus-kulcsot és a szerkesztői `default_html_tag`-et. A310 string típusú `link` prop ártalmatlan (csak tömb alakú, href-es link billent311 `a`-ra), de új widgetben ne adj ilyen nevet core-tól eltérő jelentéssel.312- **Default Styles (4.3-tól)**: az Elementor globális HTML-tag stílusai313 `.e-default-{tag}` osztályon át hatnak, amit csak a core sablonok314 `_macros.html.twig`-je rak ki. A `rendered_html`-t beillesztő Vikingo315 widgeteket NEM érintik - ez szándékos, a widget saját CSS-e dönt.316- **Elementor MCP (4.3-tól)**: minden prop típus `to_json_schema()`-t kapott,317 így a V4 widgetjeink az MCP-ben szerkeszthető elemként látszanak (a V3-at az318 MCP elutasítja). Saját prop típust ezért a core ősből származtass, hogy a319 JSON-sémája öröklődjön.320- **A `Has_Template::render()` csak `\Exception`-t nyel le, `\Error`-t nem**321 (Elementor 4.3.2): egy TypeError vagy hívás nem létező metódusra a322 `get_atomic_settings()`-ben a látogatónál végzetes hiba. A renderelő kód323 típusai legyenek szigorúan kezelve, és a próba (`\Throwable`) ezt is elkapja.324- **File:// alapú headless Chrome teszt megbízhatatlan** — vizuális325 ellenőrzéshez mindig `php -S` szerver + Playwright (channel: chrome).
Run npx get-skill add vikingokft/vikingo-elementor-atomic in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Elementor V4 atomic widget development patterns for Vikingo plugins. MUST be applied when creating or modifying Elementor widgets, dynamic tags, or editor previews in any Vikingo WordPress plugin — the atomic API (Elementor\Modules\AtomicWidgets) is undocumented and internal, so this skill captures the proven guard patterns (class_exists + experiment check + try/catch), the widget anatomy (define_props_schema, define_atomic_controls, get_atomic_settings computing rendered_html server-side), the Twig template contract, the REST-based live editor preview hydration, prop/control type reference, the post-Elementor-update checklist, and known pitfalls. Triggers on Elementor widget, atomic widget, Atomic_Widget_Base, twig template, dynamic tag, editor preview, e_atomic_elements, Elementor V4, or any vk- plugin Elementor integration. It is listed under Integrations & APIs on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
vikingokft (@vikingokft) published this skill. Their other Agent Skills are listed on their SkillMD profile.