jetelements-widgets

name	jetelements-widgets
description	Use when registering/gating a JetElements For Elementor widget, overriding its default controls/CSS/JS, adding a new shortcode, or hooking the plugin's own extension points (per-widget include/exclude-controls, custom Elementor controls, REST endpoints, carousel-options). Captures verified behavior from JetElements 2.9.1.2 source, live-verified 2026-07-16 against jackfruit.epeak.studio (7/7 tests.php assertions passing).
license	MIT
metadata	{"author":"project","version":"0.1.0"}

JetElements Widget/Addon Registration Internals

Verified facts about how JetElements For Elementor (an Elementor widget-pack addon, not a JetEngine module) registers its ~35 widgets, gates them, extends Elementor's control system, and exposes its own REST namespace. Confirmed against JetElements 2.9.1.2 source (plugins/jet-elements/).

The plugin singleton and per-subsystem singletons

Same pattern throughout the codebase: a private static $instance, a get_instance() static method, and a lowercase global accessor function — never call new ClassName() directly for any of these (see the "Gotchas" section for why one of them is unsafe to double-instantiate):

• jet_elements() → Jet_Elements::get_instance() (jet-elements.php:397-403,415-417). get_version() returns the plugin version string ('2.9.1.2', jet-elements.php:68,129-131); plugin_path( $path ) / plugin_url( $path ) resolve paths relative to the plugin root (jet-elements.php:309-330). jet_elements()->has_elementor() is just did_action( 'elementor/loaded' ) (jet-elements.php:263-265) — the plugin does nothing (widgets, controls, REST, shortcodes) until Elementor has already loaded.
• jet_elements_settings() → Jet_Elements_Settings::get_instance() (includes/class-jet-elements-settings.php:356-362,371-373). Its ->init() runs immediately at file-load time (:375, not deferred to a hook), which populates $this->avaliable_widgets (slug ⇒ display name) by globbing includes/addons/*.php and reading each file's Name/Slug/Class docblock headers via get_file_data() (:89-95) — so avaliable_widgets is already a populated array by the time any other init-hook code runs. get( $setting, $default ) reads a single flat option, get_option( 'jet-elements-settings', array() ) (:35,287-295) — there is no per-widget option row, everything (widget on/off, API keys, map provider, widgets_load_level) lives in that one option array under a different key.
• jet_elements_integration() → Jet_Elements_Integration::get_instance() (includes/class-jet-elements-integration.php:430-436,447-449). Owns widget/addon registration and Elementor control rewriting (below).
• jet_elements_assets(), jet_elements_shortocdes() (verbatim typo — "shortocdes", not "shortcodes", includes/class-jet-elements-shortcodes.php:117-119), and the advanced-map provider registries follow the identical pattern. The typo'd accessor is the real, only way to reach the shortcode registry — jet_elements_shortcodes() (correctly spelled) does not exist and will fatal with an undefined-function error.

Widget/addon registration pipeline

Jet_Elements_Integration::init() (includes/class-jet-elements-integration.php:42-71) wires the whole thing on Elementor's own hooks — version-gated because Elementor 3.5.0 renamed its registration hook:

if ( version_compare( ELEMENTOR_VERSION, '3.5.0', '>=' ) ) {
    add_action( 'elementor/widgets/register', array( $this, 'register_addons' ), 10 );
    add_action( 'elementor/widgets/register', array( $this, 'register_vendor_addons' ), 20 );
} else {
    add_action( 'elementor/widgets/widgets_registered', array( $this, 'register_addons' ), 10 );
    add_action( 'elementor/widgets/widgets_registered', array( $this, 'register_vendor_addons' ), 20 );
}

register_addons() (:112-127) globs every file in includes/addons/*.php, gates each by jet_elements_settings()->get( 'avaliable_widgets' )[ $slug ] (a widget is skipped only if the setting array exists and explicitly has that slug set falsy — ! $avaliable_widgets short-circuits to "load everything" when the setting has never been saved), then calls register_addon( $file, $widgets_manager ) (:388-404), which derives the Elementor widget class name straight from the filename: dashes→spaces→ ucwords()→underscores, namespaced Elementor\ — e.g. includes/addons/jet-elements-advanced-carousel.php → class Elementor\Jet_Elements_Advanced_Carousel, registered as ->get_name() === 'jet-carousel' (confirmed literal string at jet-elements-advanced-carousel.php:25-27 — the widget slug and the addon filename are not the same string).

register_vendor_addons() (:135-235) is a second, separate pass for integration-widgets (SmartSlider3, WooCommerce product widgets, Contact Form 7, MP Timetable, Booked Calendar/Appointments) — each entry in the jet-elements/allowed-vendor-addons filter array carries its own conditional (class_exists/defined callback) so e.g. the WooCommerce widgets never even attempt to load their addon file when WooCommerce is inactive.

Gotcha — do not call register_addons()/register_vendor_addons()/register_addon() directly from a snippet, even though they look like safe read-only registration helpers. register_addon()'s require $file; (:395) is a plain require, not require_once — on a normal request Elementor's own elementor/widgets/register hook has already fired and loaded every enabled addon's class file once. Calling any of these methods a second time re-requires an already-declared widget class, which is the same class of uncatchable "Cannot redeclare class" fatal this repo hit for real against jetsmartfilters-query's Storage\Controller (see that skill's SKILL.md and HANDOFF.md's safety lesson) — reasoned from source here, not yet live-triggered (deliberately not attempted).

Per-widget dynamic control filters

Every widget's base class constructor (Elementor\Jet_Elements_Base extends Widget_Base, includes/base/class-jet-elements-base.php:21-31) applies two dynamically-named filters keyed on the widget's own slug:

$this->_include_controls = apply_filters( "jet-elements/editor/{$widget_name}/include-controls", [], $widget_name, $this );
$this->_exclude_controls = apply_filters( "jet-elements/editor/{$widget_name}/exclude-controls", [], $widget_name, $this );

(:28-30) — e.g. to force-include or hide a specific control on just the Advanced Carousel widget: add_filter( 'jet-elements/editor/jet-carousel/include-controls', ... ). $widget_name is $this->get_name() (the slug, e.g. 'jet-carousel'), not the addon file's basename.

Custom/rewritten Elementor controls

Jet_Elements_Integration hooks elementor/controls/controls_registered twice (:56-58):

• rewrite_controls() (:295-314) unregisters and replaces Elementor's own core ICON control with Jet_Elements_Control_Icon extends Elementor\Control_Icon (includes/controls/class-jet-elements-control-icon.php:15) — a real, working example of overriding a built-in Elementor control, not just adding a new one.
• add_controls() (:322-356) registers two brand-new controls: jet_dynamic_date_time → Jet_Elements_Control_Date_Time extends Elementor\Control_Date_Time (includes/controls/class-jet-elements-control-date-time.php:17), and a grouped control jet-box-style → Jet_Group_Control_Box_Style extends Elementor\Group_Control_Base (includes/controls/groups/class-jet-group-control-box-style.php:14, registered via $controls_manager->add_group_control(), not register()). include_control( $class_name, $grouped ) (:364-379) derives the file path from the class name (class-jet-elements-control-icon.php), reading from includes/controls/groups/ only when $grouped is true.

Widget "carousel-options" pattern — reused across every slick-based widget

Every widget that wraps its items in a slick-carousel builds a plain PHP options array for the JS carousel init, then runs it through a widget-specific filter right before returning it — the reusable pattern for changing e.g. adaptive height, arrows, or autoplay without touching the widget's own controls:

• jet-elements/jet-carousel/carousel-options — Advanced Carousel, get_advanced_carousel_options(), includes/addons/jet-elements-advanced-carousel.php:2233.
• jet-elements/jet-posts/carousel-options — Posts widget's carousel-layout mode, includes/addons/jet-elements-posts.php:2490.
• jet-elements/jet-testimonials/carousel-options — includes/addons/jet-elements-testimonials.php:2781.
• jet-elements/jet-image-comparison/carousel-options — includes/addons/jet-elements-image-comparison.php:1692.
• jet-elements/slider/slider-options — the dedicated Slider widget (different naming, no jet- widget-slug segment), includes/addons/jet-elements-slider.php:3362.

All five receive ( $options_array, $settings, $widget_id ) and must return the mutated array — confirmed identical signature shape by reading each call site.

Assets: registration/enqueue hooks and override points

jet_elements_assets()->init() (includes/class-jet-elements-assets.php:33-58) hooks Elementor's own asset lifecycle, not raw wp_enqueue_scripts: elementor/frontend/before_register_styles → register_styles(), elementor/frontend/before_register_scripts → register_scripts(), elementor/frontend/before_enqueue_scripts → enqueue_scripts(), elementor/editor/before_enqueue_scripts → editor_scripts(). Every per-widget CSS/JS handle is named after the addon slug from Jet_Elements_Integration::addons_with_styles() (includes/class-jet-elements-integration.php:246-287, e.g. jet-carousel, jet-banner, jet-posts) and registered with [ 'jet-elements' ] as a dependency (class-jet-elements-assets.php:126-133) — a custom stylesheet meant to override one widget's look only needs to depend on that same handle to guarantee load order. The -skin variant stylesheet (default JetElements visual theme) is registered only when apply_filters( 'jet-elements/assets/css/default-theme-enabled', true ) is truthy (:124,135-143) — the real switch to fully opt out of JetElements' bundled skin CSS site-wide, not a per-widget setting.

REST API — jet-elements-api/v1

\Jet_Elements\Rest_Api (includes/rest-api/rest-api.php) is a singleton (get_instance(), :42-49) but the main plugin bootstraps it with a bare new \Jet_Elements\Rest_Api() instead (jet-elements.php:160) — a minor internal inconsistency, not a landmine: the constructor only does add_action( 'rest_api_init', ... ) (rest-api.php:53-55) with no unconditional require, so calling \Jet_Elements\Rest_Api::get_instance() from a snippet afterward is safe (creates a second, harmless manager object; at worst double-registers the same REST routes, which register_rest_route() tolerates). Two endpoints ship built-in, registered from init_endpoints() (:58-70), then do_action( 'jet-elements/rest/init-endpoints', $this ) (:68) — the extension point for adding a third: Endpoints\Elementor_Template (route elementor-template, used to fetch a Global Template's rendered content/id for widgets like Carousel/Slider/Dropbar that support a "load from template" item type — see their own jet-elements/widgets/template_id / template_content filters) and Endpoints\Plugin_Settings (route plugin-settings, backs the admin Settings page's save/load AJAX). Every endpoint class extends abstract Endpoints\Base (includes/rest-api/endpoints/base.php), defaulting permission_callback() to current_user_can( 'manage_options' ) (:43-45) unless overridden.

Shortcodes — a second, non-Elementor entry point

jet_elements_shortocdes()->register_shortcodes() (hooked on init, priority 30, includes/class-jet-elements-shortcodes.php:42-59) globs includes/shortcodes/*.php the same filename→class-name way widgets do, instantiates each, and stores it keyed by ->get_tag(). As of 2.9.1.2 there is exactly one shortcode, [jet-posts] (Jet_Posts_Shortcode, includes/shortcodes/jet-posts-shortcode.php:5,18-20, extending abstract Jet_Elements_Shortcode_Base, includes/base/class-jet-elements-shortcode-base.php:7) — a fully independent implementation of the Posts widget usable outside Elementor entirely (in classic content, a template via do_shortcode(), etc). Its attribute schema is filterable via jet-elements/shortcodes/jet-posts/atts (jet-posts-shortcode.php:35), and its render loop fires four of its own hooks distinct from the widget's Query-Gateway hooks (see jetelements-query-gateway): jet-elements/shortcodes/jet-posts/loop-start, loop-item-start, loop-item-end, loop-end (:729,743,750,759).

Gotchas

• jet_elements_shortocdes() — the misspelling is load-bearing, not a doc error; the correctly-spelled function genuinely doesn't exist.
• Never call register_addons()/register_vendor_addons()/register_addon() directly — re-requires already-declared widget classes on any request past the first (see "Widget/addon registration pipeline" above).
• A widget's Elementor-facing slug (get_name(), e.g. 'jet-carousel') is not the same string as its addon filename slug (jet-elements-advanced-carousel) used for the avaliable_widgets settings-gating key — don't assume get_name() matches basename( $file, '.php' ).
• widgets_load_level (Elements_Base::$_load_level, includes/base/class-jet-elements-base.php:24) is a JetStyleManager-compatibility integration point (register_for_styles_manager(), class-jet-elements-settings.php:112-114), not a per-widget individual toggle — it's a single global "how much CSS to preload" setting.

How this was verified

Read jet-elements.php, includes/class-jet-elements-integration.php, includes/class-jet-elements-settings.php, includes/class-jet-elements-assets.php, includes/class-jet-elements-shortcodes.php, includes/base/class-jet-elements-base.php, includes/base/class-jet-elements-shortcode-base.php, includes/shortcodes/jet-posts-shortcode.php, includes/controls/class-jet-elements-control-icon.php, includes/controls/class-jet-elements-control-date-time.php, includes/controls/groups/class-jet-group-control-box-style.php, includes/rest-api/rest-api.php, includes/rest-api/endpoints/base.php, and includes/rest-api/endpoints/elementor-template.php in JetElements 2.9.1.2 source (plugins/jet-elements/), plus grepping every jet-elements/* hook across includes/addons/*.php to confirm the carousel-options pattern's five real call sites. Cross-checked the one gist already logged in other-plugins-backlog/OTHER-PLUGINS.md's "JetElements" section (jet-elements/jet-carousel/carousel-options, adaptive-height gist) — confirmed as a real hook, folded into the broader carousel-options section above rather than documented standalone. Not yet verified against a running site — JetElements was not installed on the sandbox as of this writing (see TEST-REGIMEN.md); tests.php is written as reachability/source-presence smoke tests ready to run once it is.