MageOS AdvancedWidget Module for Magento

Add configurable multi-row CMS Widgets with image picker component, product picker component, select fields and much more.

Overview

The AdvancedWidget module allows you to define multi-row CMS widgets.
These features combined with MageOS_PageBuilderWidget module (that is explicit dependency) make finally possible to develop custom pagebuilder components with own preview and a large set of configurations.
Complex pagebuilder ui components development is no more needed.

🚀 Features

1. This module let you specify Title separators inside widgets
   [image: title section]

1. This module let you specify multiple "repeatable" sections where you can specify unlimited rows inside widgets
   [image: repeatable section]

2.1) Each item field can receive a dedicated tooltip
[image: repeatable section]

2.2) Each field is validated and ask to be required for compilation
[image: repeatable section]

2.3) Items can be sorted
[image: repeatable section]

2.4) You can specify whether a field is editable directly in the main box or whether it must be edited in the detail modal.
[image: repeatable section]

1. Row item images fields are available
   [image: image field]
   [image: image field selection]

1. Row item select fields are available
   [image: select field]

1. Row item product fields are available
   [image: product field]
   [image: product field selection]

1. Row item wysiwyg and colorpicker fields are also available (see the field reference below)

📖 Field reference

Two kinds of fields exist:

1. Widget parameter fields — declared in your module's etc/widget.xml as xsi:type="block" parameters pointing at a renderer class from MageOS\AdvancedWidget\Block\WidgetField\*. On the frontend the value arrives as plain block data ($block->getData('name')).
2. Repeatable row fields — declared in PHP inside a Rows subclass; editors can add, sort and delete unlimited rows, each row containing these fields.

Widget parameter fields

Image — Block\WidgetField\Image

Renders a text input with a "Choose Image..." button that opens the Magento media gallery browser. Stores the media-relative path (e.g. wysiwyg/hero/image.jpg) as a plain string.

<parameter name="image" sort_order="10" required="true" visible="true" xsi:type="block">
    <label translate="true">Image</label>
    <block class="MageOS\AdvancedWidget\Block\WidgetField\Image">
        <data>
            <item name="button" xsi:type="array">
                <item name="open" xsi:type="string">Choose image...</item>
            </item>
        </data>
    </block>
</parameter>

On the frontend, resolve the stored path with $block->getImageUrl('image') (from Block\Widgets\AbstractColumns) — it prefixes the store media base URL when the value isn't already absolute.

TextArea — Block\WidgetField\TextArea

Plain multi-line text input (no HTML editor). Line breaks are preserved in the stored value.

<parameter name="description" sort_order="20" required="false" visible="true" xsi:type="block">
    <label translate="true">Description</label>
    <block class="MageOS\AdvancedWidget\Block\WidgetField\TextArea"/>
</parameter>

WYSIWYG — Block\WidgetField\Wysiwyg

Full TinyMCE editor (variables and images enabled, nested widgets disabled). The stored value is HTML — don't escapeHtml it on the frontend; sanitize it instead, e.g. with Block\Widgets\Template::stripTags(), which ships with a sensible default tag whitelist.

<parameter name="content" sort_order="30" required="false" visible="true" xsi:type="block">
    <label translate="true">Rich content</label>
    <block class="MageOS\AdvancedWidget\Block\WidgetField\Wysiwyg"/>
</parameter>

Title separator — Block\WidgetField\Title

Purely visual: renders a heading/divider inside the widget form to group fields. It stores no meaningful value — the displayed text comes from the parameter's <description>. Don't read this parameter on the frontend.

<parameter name="section_title" sort_order="40" required="false" visible="true" xsi:type="block">
    <label translate="true"> </label>
    <description translate="true"><![CDATA[<h2>Content</h2><hr/>]]></description>
    <block class="MageOS\AdvancedWidget\Block\WidgetField\Title"/>
</parameter>

Repeatable rows — Block\WidgetField\Rows

The headline feature: unlimited sortable rows, each with its own field set. The parameter name must start with repeatable_ — both the save plugin (Plugin\SaveRepeatableItems) and the admin renderer detect repeatable values by that prefix. A widget can have several repeatable parameters, each with its own Rows subclass.

<parameter name="repeatable_items" xsi:type="block" sort_order="50" required="false" visible="true">
    <label translate="true">Items</label>
    <block class="Vendor\Module\Block\Widget\Repeatable\CardItem"/>
</parameter>

Repeatable row fields

Extend MageOS\AdvancedWidget\Block\WidgetField\Rows and fill the $rows property — an ordered map of field_key => config:

class CardItem extends \MageOS\AdvancedWidget\Block\WidgetField\Rows
{
    protected $rows = [
        'title' => [
            'label' => 'Title',
            'type' => 'text',
            'required' => true,
            'preview' => true,
        ],
        'image' => [
            'label' => 'Image',
            'type' => 'image',
            'preview' => true,
        ],
        'style' => [
            'label' => 'Card style',
            'type' => 'select',
            'options' => [
                'light' => 'Light',
                'dark' => 'Dark',
            ],
            'preview' => false,
        ],
        'background' => [
            'label' => 'Background color',
            'type' => 'colorpicker',
            'default' => '#1E88E5',
            'description' => 'Shown as a tooltip next to the field.',
            'preview' => false,
        ],
    ];
}

Row config keys

Row field types

Notes:

• text and textarea are built in; select, image, product, wysiwyg and colorpicker are registered as custom field types in etc/adminhtml/di.xml (the customFields argument of Block\Adminhtml\Renderer\Repeatable). Third-party modules can register additional types through the same DI argument — each entry pairs a type name with a JS component and a .phtml partial.
• product: the field key must start with product — the admin renderer then auto-populates the sibling display keys <field>_sku, <field>_name and <field>_image for the row list. On the frontend, load the product from the stored ID; ViewModel\ProductData::getProductById() does this and pre-resolves mageos_main_image, mageos_swatch_image, mageos_small_image and mageos_thumb_image URLs on the product.

Reading values on the frontend

Extend MageOS\AdvancedWidget\Block\Widgets\AbstractColumns in your widget block:

foreach ($this->getRepeatableField('repeatable_items') as $item) {
    $title = $item['title'] ?? '';
    $image = $this->getImageUrlByPath($item['image'] ?? '');
    // ...
}

Available helpers:

🔧 Installation

1. Install it into your Mage-OS/Magento 2 project with composer:

   composer require mage-os/module-advanced-widget
   

2. Enable module

   bin/magento module:enable MageOS_AdvancedWidget
   bin/magento setup:upgrade
   

🤝 Changelog

Please see CHANGELOG for more information on what has changed recently.

📄 License

The MIT License (MIT). Please see License File for more information.

Attribution

This software uses Open Source software. See the ATTRIBUTION page for these projects.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog
and this project adheres to Semantic Versioning.

1.2.4

Added

• Colorpicker repeatable field: configurable starting color via a default row config key ('default' => '#RRGGBB' or an rgba(...) value). When omitted it still falls back to #FFFFFF.

Fixed

• sync correctly colorpicker values sync between preview and modal
• wysiwyg field now shows a limited number of elements on the toolbar

1.2.3

Fixed

• Remove debugging code

1.2.2

Fixed

• Change declaration for properties

1.2.1

Fixed - Added

• Add wysiwyg and color repeatable component types
• Fix fatal error on redeclaration for properties removing protected attribute from $rawResultFactory and $getInsertImageConten. Thanks to @Sental

1.2.0 - 2026-04-21

Fixed

• PHP 8.5 compatibility: cast nullable values to string before passing to str_replace, strpos, str_contains, preg_match, explode, urldecode and similar string functions to avoid deprecation notices and fatal errors
• Cast nullable values to string/int before using as array index (PHP 8.5 null array key deprecation)
• Replace deprecated strpos / strpos(..., 'http') === false usages with str_starts_with / str_contains
• Add declare(strict_types=1) and missing return type hints to Controller/Adminhtml/Image/Chooser
• Clean up redundant $this->escaper = $escaper ?: ObjectManager::getInstance()->get(...) fallback in Controller/Adminhtml/Product/Widget/Chooser (constructor already enforces non-null Escaper)

Changed

• Change remaining private promoted/regular properties to protected for consistent extensibility across all classes

1.1.2

Fixed

• Fix getRowClickCallback() returning null instead of string when massaction is enabled
• Change private constructor properties to protected for extensibility

1.1.1

Fixed

• Unset missing products from repeatable fields during widget configuration rendering

1.1.0

Updated

• Update composer JSON making the module installable for Magento Opensource also

1.0.0

Added

• First Commit, now is possible to define CMS widgets with multiple row fields!