Custom Elementor Widgets

The suma-elementor theme registers a library of custom Elementor widgets and dynamic tags tailored for precious metals e-commerce.

Registration: \Suma\Theme\Elementor_Widgets class (inc/class-elementor-widgets.php) Widget source files: inc/widgets/ Tag source files: inc/tags/ Skin files: inc/skins/

---

How Widgets Are Registered

// In class-elementor-widgets.php
add_action( 'elementor/widgets/register', [ $this, 'register_custom_widgets' ] );
add_action( 'elementor/dynamic_tags/register', [ $this, 'register_dynamic_tags' ] );

All custom widgets extend Elementor's \Elementor\Widget_Base or WooCommerce product widget classes.

---

Custom Widget Categories

Custom widgets appear in the Elementor panel under the following categories:

• Suma Widgets — General purpose custom widgets
• Suma Products — Product display widgets
• Suma Account — Customer account widgets
• Suma Pricing — Precious metals pricing display widgets

---

Key Custom Widgets

Product Pricing Widget

Displays the current price of a precious metal product including:

• Spot price component
• Premium component
• Total price
• Price-per-ounce breakdown

Updates automatically with the 1-minute price refresh.

---

Live Spot Price Ticker

Displays real-time spot prices for gold, silver, platinum, and palladium. Fetches from the NFusion live price chart API.

---

Metal Price Calculator Widget

Provides a front-end calculator for converting metal quantity and spot price into estimated value.

• Supports metal selection for gold, silver, and platinum.
• Uses the same pricing data source patterns as other pricing widgets.
• Useful for educational/marketing pages where users want quick bullion value estimates.

---

User Dashboard Stats Widget

Displays account-level year-to-date metrics for logged-in customers, including:

• Total orders YTD
• Total paid/unpaid totals
• Gold ounces YTD
• Silver ounces YTD
• Platinum ounces YTD
• Total items YTD

Implementation lives in inc/widgets/user-dashboard-stats/ and computes metal ounces from ordered product _metal_weight and _metal_type values.

---

Product Slider Widget

Renders a horizontally scrollable Swiper carousel of WooCommerce products.

Source: inc/widgets/product-slider/ Widget type: product-slider

Query Modes

Mode	Description
filters	Filters by WooCommerce product category and/or product attributes (pa_* taxonomies)
manual	Shows a hand-picked list of product IDs
cross-sells	Shows cross-sell products for the current product or cart items
up-sells	Shows up-sell products for the current product or cart items
popular	Shows most-purchased products over a configurable rolling day window
algolia-*	Pulls recommendations from Algolia Recommend

Key Settings

Setting	Purpose
product_category	WooCommerce product category slug to filter by
attr_*	One entry per registered pa_* taxonomy (e.g. attr_special-status) — multi-select terms to filter by
show_outofstock	Whether out-of-stock products appear in results (yes/no)
hide_unavailable_products	Hides products with _mint_status of coming_soon, out_of_mint, or suspended
empty_result_mode	What to do when no products match: "" = hide widget, hide_parent = remove a parent CSS selector
num_products	Max products to return

Empty Result Behaviour

When the query returns zero products the PHP layer passes an empty data-products="[]" attribute to the JS. The JavaScript (AppLazy.js → loadProducts()) then:

1. Falls back to Algolia Recommend if query_mode starts with algolia.
2. If still empty and not in Elementor editor mode, removes the widget (or a parent element if empty_result_mode = hide_parent with a CSS selector configured).

Important: The widget does not fall back to showing random products. If products unexpectedly appear, see Troubleshooting.

Deleted Attribute Auto-Cleanup

When a WooCommerce product attribute is deleted and a product-slider widget still references it in attr_* settings, Elementor keeps the stale data in _elementor_data even after saving. This causes the widget to filter by a non-existent taxonomy, producing zero results.

The widget hooks into elementor/document/save/data to automatically strip any attr_* setting whose taxonomy no longer exists in WooCommerce:

// Product_Slider::sanitize_deleted_attribute_filters()
// Fires on every Elementor document save and removes attr_* keys
// that reference deleted WooCommerce attribute taxonomies.
add_filter( 'elementor/document/save/data', [ $this, 'sanitize_deleted_attribute_filters' ] );

Re-saving a page in Elementor after a WooCommerce attribute is deleted will clean the widget automatically.

---

Product Grid Widget

Advanced WooCommerce product grid with:

• Lazy loading
• AJAX pagination
• Integrated Algolia filtering
• Sort options (price, popularity, metal type, weight)
• Category-level spot price display

Source: inc/widgets/product-grid/ Widget type: product-grid

The product grid uses the same attr_* filter pattern and the same deleted-attribute auto-cleanup hook as the Product Slider widget.

---

Cart Icon Widget

Displays a dynamic cart icon with current item count. Updates via real-time AJAX when items are added/removed.

Implementation: [wc-cart-icon] shortcode wrapped in an Elementor widget.

---

Order Tracking Widget

Embeds the [suma_order_tracking] shortcode from the suma-woo-order-tracking plugin.

---

Dealer Locator Widget

Embeds the dealer locator map with configurable filtering options.

---

Yotpo Reviews Widget

Embeds the Yotpo product reviews widget with configurable display options (star rating, review count, review list).

---

Wishlist Button Widget

A styled YITH Wishlist button matching the Scottsdale Mint design system.

---

Custom Dynamic Tags

Dynamic tags allow Elementor users to bind widget content to dynamic data sources:

Tag	Output	Use Case
Product Spot Price	Current spot price for a metal type	Price display on product pages
Product Metal Weight	Product's troy oz content	Product detail pages
Product Premium	Premium over spot	"X% over spot" displays
Current Order Status	Status of current user's most recent order	Confirmation pages
Customer Total Spent	Lifetime order value of the current customer	Account pages

---

Widget Build System

The theme includes a separate build process for widget-specific JavaScript and CSS:

# Build all widget bundles
./build-widgets.sh

# Or on Windows
build-widgets.bat

Widget assets are output separately from the global dist/ build to allow Elementor to load them on-demand (per-widget lazy loading).

---

Elementor Editor Bullion Helper

In Elementor edit mode, the theme adds a custom Add Bullion button to the Text Editor toolbar (src/js/Editor.js).

This helper inserts a bullion conversion span and includes Platinum in the metal selector options alongside Gold and Silver.

---

Adding a New Custom Widget

1. Create inc/widgets/class-{widget-slug}-widget.php extending \Elementor\Widget_Base
2. Implement required methods:
   • get_name() — Widget slug
   • get_title() — Display name in Elementor panel
   • get_icon() — Elementor icon class
   • get_categories() — Panel category
   • _register_controls() — Widget settings fields
   • render() — Front-end HTML output
   • content_template() — Elementor editor preview template
3. Register in class-elementor-widgets.php:

   $widgets_manager->register( new \Suma\Widgets\My_New_Widget() );

4. Add any widget-specific SCSS to src/scss/widgets/
5. Run ./build-widgets.sh to compile