magento2-widget-creation_skill

Overview

This skill is a practical guide for creating custom Magento 2 widget modules that editors can insert into CMS pages and blocks. It focuses on standard Magento themes (Luma/Blank) and covers module structure, widget configuration, block logic, templates, JavaScript behavior, CSS loading, and form/AJAX handling. Follow it to build reusable, configurable content components for non-technical users.

How this skill works

The guide walks through the files and XML entries a widget needs: module registration, module.xml, and etc/widget.xml to declare parameters. It shows how to implement a Block class that exposes parameter getters and URLs, create a secure PHTML template that escapes output and initializes JS, and optionally add requirejs mapping, a jQuery UI-style widget script, controllers for form submissions, and frontend CSS. The approach separates presentation from logic and uses Magento widget parameters to make components configurable in admin.

When to use it

• You need a reusable content component editors can add to CMS pages or blocks
• You want configurable UI elements (text, selects, yes/no, block/page choosers) available in the admin widget inserter
• You need interactive widgets with JavaScript-driven behavior and optional AJAX/form submission
• You must target standard Magento themes (Luma/Blank) rather than Hyvä
• You want a pattern that keeps business logic in Block classes and simple markup in templates

Best practices

• Declare strict types and type-hint method signatures in PHP classes
• Implement Magento\Widget\Block\BlockInterface and use $this->getData('param') with sensible defaults
• Always escape user-facing output in templates: escapeHtml, escapeHtmlAttr, escapeJs, escapeUrl, escapeCss
• Generate unique IDs in templates (uniqid) to avoid collisions when multiple widgets appear
• Keep logic in Block methods; templates should handle presentation only
• Use requirejs-config.js to map JS and Magento widget pattern for interaction and AJAX

Example use cases

• A promo banner widget with editable headline, CTA text, and CTA variant select
• An interactive lead form widget that posts to a frontend controller and returns JSON
• A CMS-choosable content block widget that lets editors place predefined blocks with extra options
• A category-linked widget that shows curated content based on a category_id parameter
• A small modal or carousel widget initialized via Magento JS widget pattern