magento2-widget-creation

This skill provides comprehensive guidance on creating custom widget modules in Magento 2 (standard Luma/Blank themes, not Hyvä-based) that can be inserted into CMS pages, CMS blocks, or any content area using the widget system.

Use this skill when you need to:

• Create a reusable component that can be inserted into CMS pages
• Build interactive elements (buttons, forms, modals) for content editors
• Develop custom functionality that non-technical users can add to pages
• Create widgets with configurable parameters that appear in the admin panel
• Implement widgets that work with standard Magento themes (Luma/Blank)

Do NOT use this skill for:

• Hyvä theme widgets (use hyva-tailwind-integration skill instead)
• Backend admin widgets
• UI components or admin grids

• Existing vendor namespace or willingness to create one
• Basic understanding of Magento 2 module structure
• Knowledge of XML configuration
• Familiarity with Magento templates and blocks
• Understanding of JavaScript widget pattern (optional, for interactive widgets)

A complete widget module requires these components:

```

app/code/Vendor/ModuleName/

├── registration.php # Module registration

├── etc/

│ ├── module.xml # Module configuration

│ ├── widget.xml # Widget definition

│ ├── email_templates.xml # (Optional) Email templates

│ └── frontend/

│ └── routes.xml # (Optional) For form submissions

├── Block/

│ └── Widget/

│ └── WidgetName.php # Widget block class

├── Controller/ # (Optional) For form handlers

│ └── Index/

│ └── Submit.php

└── view/frontend/

├── templates/

│ └── widget/

│ └── template.phtml # Widget template

├── layout/

│ └── default.xml # (Optional) Load CSS/JS globally

├── web/

│ ├── js/

│ │ └── widget-script.js # (Optional) Custom JS

│ └── css/

│ └── widget-style.css # (Optional) Custom CSS

├── requirejs-config.js # (Optional) JS module mapping

└── email/ # (Optional) Email templates

└── template.html

```

Step 1: Create Module Registration

File: registration.php

```php

/**

* Copyright © Vendor. All rights reserved.

*/

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(

ComponentRegistrar::MODULE,

'Vendor_ModuleName',

__DIR__

);

```

Step 2: Create Module Configuration

File: etc/module.xml

```xml

xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">

```

Key Points:

• setup_version is legacy but still commonly used
• Add dependencies in - Magento_Cms and Magento_Widget are required for widgets
• Add other modules your widget depends on (e.g., Magento_Email, Magento_Catalog)

Step 3: Create Widget Configuration

File: etc/widget.xml

This is where you define your widget's metadata and configurable parameters.

```xml

xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Widget:etc/widget.xsd">

Widget Display Name

Brief description of what the widget does

Text Label

Description shown in admin

Select Option

Option 1

Option 2

source_model="Magento\Config\Model\Config\Source\Yesno">

Enable Feature

CMS Block

Select Block...

source_model="Magento\Catalog\Model\Category\Attribute\Source\Categories">

Category

```

Widget Parameter Types:

• text - Simple text input
• select - Dropdown selection
• multiselect - Multiple selections
• block - CMS block picker
• page - CMS page picker
• conditions - Product/category conditions (advanced)

Important Attributes:

• id - Unique identifier for the widget
• class - Full namespaced path to your block class
• required - Whether parameter is mandatory
• visible - Whether parameter shows in admin

Step 4: Create Block Class

File: Block/Widget/WidgetName.php

The block class handles the widget's logic and data.

```php

/**

* Copyright © Vendor. All rights reserved.

*/

declare(strict_types=1);

namespace Vendor\ModuleName\Block\Widget;

use Magento\Framework\View\Element\Template;

use Magento\Widget\Block\BlockInterface;

use Magento\Framework\View\Element\Template\Context;

class WidgetName extends Template implements BlockInterface

{

/**

* Template path relative to view/frontend/templates/

*

* @var string

*/

protected $_template = 'Vendor_ModuleName::widget/template.phtml';

/**

* @param Context $context

* @param array $data

*/

public function __construct(

Context $context,

array $data = []

) {

parent::__construct($context, $data);

}

/**

* Get widget parameter with default value

*

* @return string

*/

public function getParameterValue(): string

{

return $this->getData('text_param') ?: 'default value';

}

/**

* Get widget select parameter

*

* @return string

*/

public function getSelectValue(): string

{

return $this->getData('select_param') ?: 'value1';

}

/**

* Check if feature is enabled

*

* @return bool

*/

public function isEnabled(): bool

{

return (bool)$this->getData('enabled');

}

/**

* Get URL for AJAX or form submission

*

* @return string

*/

public function getActionUrl(): string

{

return $this->getUrl('modulename/index/submit');

}

}

```

Best Practices:

• Always declare(strict_types=1);
• Implement BlockInterface
• Use $this->getData('param_name') to access widget parameters
• Provide default values with ?: operator
• Add type hints and return types
• Keep business logic out of templates - put it in block methods

Step 5: Create Template File

File: view/frontend/templates/widget/template.phtml

Templates render the HTML output. Always escape data for security.

```php

/**

* Copyright © Vendor. All rights reserved.

*

* @var $block Vendor\ModuleName\Block\Widget\WidgetName

* @var $escaper Magento\Framework\Escaper

*/

$paramValue = $block->getParameterValue();

$selectValue = $block->getSelectValue();

$isEnabled = $block->isEnabled();

$uniqueId = uniqid('widget_');

?>

```

Template Best Practices:

• Always use $escaper->escapeHtml() for text content
• Use $escaper->escapeHtmlAttr() for HTML attributes
• Use $escaper->escapeJs() for JavaScript strings
• Use $escaper->escapeUrl() for URLs
• Use __() for translatable strings
• Generate unique IDs to avoid conflicts (use uniqid())
• Add proper @var comments for IDE support

Common Escaping Methods:

```php

// Text content

escapeHtml($text) ?>

// HTML attributes