suma-blocks

Custom Elementor widget library for TenPoint Crossbows page building.

Overview

Version: 1.2.0
Purpose: Provides custom Elementor widgets for building TenPoint-specific page layouts and features
Namespace: Suma\Blocks
Requires: Elementor ≥ 2.0.0, PHP ≥ 7.0

Features

• Custom Elementor widget category ("suma")
• Specialized crossbow product display widgets
• Video embed enhancements
• Custom styling and layout options
• Integration with other Suma plugins

File Structure

suma-blocks/
├── suma-blocks.php          # Entry point with Base class
├── inc/
│   └── class-utils.php      # Utility functions
├── assets/
│   ├── css/                 # Widget stylesheets
│   └── js/                  # Widget JavaScript
└── README.md

Main Class: Base

Located in suma-blocks.php, the Base class extends Elementor's plugin system.

Version Constant

define('SUMA_BLOCKS_VERSION', '1.2.0');

Hooks Used

Hook	Priority	Callback	Purpose
plugins_loaded	10	load_blocks()	Initialize block loading
save_post	10	clear_save_video_transient()	Clear video cache on post save
wp_enqueue_scripts	10	add_styles_and_scripts()	Enqueue frontend assets
elementor/elements/categories_registered	10	register_widget_categories()	Register "suma" category
elementor/widgets/widgets_registered	10	register_blocks()	Register custom widgets

Custom Widget Category

Creates a dedicated "suma" category in Elementor's widget panel for easy identification of custom blocks.

$elements_manager->add_category(
    'suma',
    [
        'title' => __('Suma', 'suma-blocks'),
        'icon'  => 'fa fa-plug',
    ]
);

Available Widgets

Custom Elementor widgets are registered and available in the Elementor editor under the "Suma" category.

Widget Registration

Widgets are dynamically loaded from the inc/ directory using the naming convention:

inc/class-{widget-name}-widget.php

Each widget class:

• Extends \Elementor\Widget_Base
• Defines controls for customization
• Renders output based on control values
• Includes responsive design options

Video Transient Management

The plugin manages video-related transients to ensure fresh data after content updates.

Clear Video Transient Function

public function clear_save_video_transient($post_id) {
    // Triggered on save_post
    // Clears cached video data for the updated post
}

Assets Management

CSS Enqueue

Custom widget stylesheets are enqueued on the frontend:

wp_enqueue_style(
    'suma-blocks-style',
    plugins_url('assets/css/suma-blocks.css', __FILE__),
    [],
    SUMA_BLOCKS_VERSION
);

JavaScript Enqueue

Custom widget scripts for enhanced interactivity:

wp_enqueue_script(
    'suma-blocks-script',
    plugins_url('assets/js/suma-blocks.js', __FILE__),
    ['jquery', 'elementor-frontend'],
    SUMA_BLOCKS_VERSION,
    true
);

Integration with Other Plugins

suma-videos Integration

• Respects video transient caching
• Clears video cache when posts are updated
• Ensures fresh video data in Elementor widgets

suma-cross-sells Integration

• Works alongside cross-sell functionality
• Shares product display patterns

Usage in Elementor

1. Open a page in Elementor editor
2. Look for the "Suma" category in the widgets panel
3. Drag desired widget onto the canvas
4. Configure widget settings in the left sidebar
5. Preview and publish

Development

Adding New Widgets

To add a new custom widget:

1. Create widget class file in inc/:

   inc/class-my-widget-widget.php

2. Define widget class extending \Elementor\Widget_Base:

   namespace Suma\Blocks;
   
   class My_Widget_Widget extends \Elementor\Widget_Base {
       
       public function get_name() {
           return 'suma_my_widget';
       }
   
       public function get_title() {
           return __('My Widget', 'suma-blocks');
       }
   
       public function get_icon() {
           return 'eicon-posts-grid';
       }
   
       public function get_categories() {
           return ['suma'];
       }
   
       protected function register_controls() {
           // Define widget controls
       }
   
       protected function render() {
           // Output widget HTML
       }
   }

3. Register widget in Base::register_blocks():

   $widgets_manager->register_widget_type(new \Suma\Blocks\My_Widget_Widget());

Widget Control Types

Common Elementor control types used in Suma widgets:

Control Type	Purpose	Example
TEXT	Single-line text input	Title, heading
TEXTAREA	Multi-line text input	Description, content
NUMBER	Numeric input	Count, limit
SELECT	Dropdown selection	Layout type, alignment
COLOR	Color picker	Text color, background
MEDIA	Image/video upload	Featured image
REPEATER	Repeatable fields	List items, slides
SLIDER	Range slider	Spacing, size

Responsive Controls

Many controls support responsive settings:

$this->add_responsive_control(
    'columns',
    [
        'label'   => __('Columns', 'suma-blocks'),
        'type'    => \Elementor\Controls_Manager::SELECT,
        'default' => '3',
        'options' => [
            '1' => '1',
            '2' => '2',
            '3' => '3',
            '4' => '4',
        ],
        'selectors' => [
            '{{WRAPPER}} .grid' => 'grid-template-columns: repeat({{VALUE}}, 1fr);',
        ],
    ]
);

Styling Best Practices

CSS Naming Convention

Use BEM (Block Element Modifier) naming:

.suma-widget {}
.suma-widget__element {}
.suma-widget__element--modifier {}

Responsive Design

/* Mobile first */
.suma-widget {
    /* Mobile styles */
}

@media (min-width: 768px) {
    .suma-widget {
        /* Tablet styles */
    }
}

@media (min-width: 1024px) {
    .suma-widget {
        /* Desktop styles */
    }
}

Performance Considerations

• Transient caching: Video and product data cached to reduce database queries
• Lazy loading: Images lazy-loaded by default
• Minimal dependencies: Only essential scripts enqueued
• Conditional loading: Assets only loaded when widget is used

Troubleshooting

Widgets Not Showing

• Verify Elementor is active and minimum version met
• Check PHP version (7.0+)
• Clear Elementor cache: Elementor → Tools → Regenerate CSS

Styling Issues

• Regenerate Elementor CSS
• Check for theme CSS conflicts
• Verify custom CSS enqueued properly

JavaScript Errors

• Check browser console for errors
• Verify jQuery dependency loaded
• Ensure Elementor frontend scripts loaded

Version History

v1.2.0 (Current)

• Enhanced video transient management
• Improved Elementor integration
• Updated for Elementor 3.x compatibility

Related Documentation

• suma-dealer-locator — Dealer locator integration
• Theme Overview