Vikingo Elementor Atomic

Vikingo – Elementor V4 atomic widget minták

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.

1. Referencia-források (helyi gépen)

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: 4.2.1.)

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:

$experiments = \Elementor\Plugin::$instance->experiments;
$atomic_ok   = $experiments && $experiments->is_feature_active( 'e_atomic_elements' );

é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.

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)

• Select_Control::set_options() formátuma: array( array( 'value' => 'x', 'label' => 'X' ), … ) — NEM kulcs=>érték!
• 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, base_styles. 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:

1. 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.
2. 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.
3. 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.
• A Has_Template::render() twig kontextus-kulcsai változatlanok-e (id, interaction_id, type, settings, base_styles).
• A használt controlok (Select_Control::set_options formátum!) és prop típusok megvannak-e.
• Az e_atomic_elements experiment neve/állapota változott-e (modules/atomic-widgets/module.php, EXPERIMENT_NAME).
• Éles teszt: widget behúzása a szerkesztőben, beállítás-változtatás (hidratálás frissül-e), mentés, frontend render, shortcode render.
• ELEMENTOR_DEBUG bekapcsolásával nincs-e lenyelt twig-kivétel.

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.
• File:// alapú headless Chrome teszt megbízhatatlan — vizuális ellenőrzéshez mindig php -S szerver + Playwright (channel: chrome).