Skip to content
Skills Library
Programming · Building & coding

widget

/widget

Scaffold a Magento 2 CMS widget on an existing module: `etc/widget.xml`, a block with typed parameters and a cache key, a `.phtml` template, and tests. Use for 'add a widget', 'create a widget.xml', 'make X insertable from Content → Widgets, the WYSIWYG editor, or a widget directive in CMS content'. NOT for jQuery-UI `$.widget` / Breeze JS widgets: use magento2-tools:frontend (RequireJS / Knockout / Alpine) or magento2-tools:breeze-adapt. For a new module use magento2-tools:module-create first.

Licence
MIT
Last repository change
04.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
3
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: templates/test-widget-block-unit.php, templates/test-widget-declaration-integration.php, templates/widget-block.php

What it does and when to use it

Scaffold a Magento 2 CMS widget on an existing module: `etc/widget.xml`, a block with typed parameters and a cache key, a `.phtml` template, and tests. Use for 'add a widget', 'create a widget.xml', 'make X insertable from Content → Widgets, the WYSIWYG editor, or a widget directive in CMS content'. NOT for jQuery-UI `$.widget` / Breeze JS widgets: use magento2-tools:frontend (RequireJS / Knockout / Alpine) or magento2-tools:breeze-adapt. For a new module use magento2-tools:module-create first.

Triggers from the description

add a widgetcreate a widget.xml
Original author description

Scaffold a Magento 2 CMS widget on an existing module: `etc/widget.xml`, a block with typed parameters and a cache key, a `.phtml` template, and tests. Use for 'add a widget', 'create a widget.xml', 'make X insertable from Content → Widgets, the WYSIWYG editor, or a widget directive in CMS content'. NOT for jQuery-UI `$.widget` / Breeze JS widgets: use magento2-tools:frontend (RequireJS / Knockout / Alpine) or magento2-tools:breeze-adapt. For a new module use magento2-tools:module-create first.

How it works

  1. Core Rules
  2. Workflow
  3. Inputs
  4. Outputs
  5. Reference Files
  6. Templates
  7. Acceptance Criteria
  8. Related Skills
Original SKILL.md headings · 282 lines, 2,067 words
SKILL.md preview
---
name: widget
version: 1.0.1
description: >-
  Scaffold a Magento 2 CMS widget on an existing module: `etc/widget.xml`, a block with typed
  parameters and a cache key, a `.phtml` template, and tests. Use for 'add a widget', 'create a
  widget.xml', 'make X insertable from Content → Widgets, the WYSIWYG editor, or a widget directive
  in CMS content'. NOT for jQuery-UI `$.widget` / Breeze JS widgets: use magento2-tools:frontend
  (RequireJS / Knockout / Alpine) or magento2-tools:breeze-adapt. For a new module use
  magento2-tools:module-create first.
---

# Magento 2 CMS Widget Scaffold

Scaffold a CMS widget onto an **existing** Magento 2 module. A widget is a block that a
store admin can drop onto pages without touching code — from **Content → Widgets** (a
*widget instance* bound to layout containers), from the WYSIWYG editor's *Insert Widget*
button, or from a `{{widget type="..." ...}}` directive inside CMS page/block content.
Produces `etc/widget.xml`, the `Magento_Widget` dependency, the block class, the storefront
template, and the tests that prove the parameter contract.

## Core Rules

- **Widget id convention:** `{vendor_lower}_{module_lower}_{widget}` — all lowercase,
  underscore-separated, where `{vendor_lower}` / `{module_lower}` are the snake_case forms
  from `context/references/naming.md` (`OrderExport` → `order_export`) and `{widget}` is
  the snake_case widget class name **minus a duplicated leading `{module_lower}_`**:
  `Acme_Promo` + `PromoBanner` → `acme_promo_banner`; `Acme_Promo` + `Countdown` →
  `acme_promo_countdown`. The id is an `xs:ID` in the merged widget config of every
  module on the instance, so the vendor + module prefix is what keeps it collision-free.
- **The block contract.** The class extends `Magento\Framework\View\Element\Template` and
  implements `Magento\Widget\Block\BlockInterface` (the marker the widget filter checks
  before rendering; a block without it renders as an empty string). `$_template` holds the
  fully-qualified path `{Vendor}_{Module}::widget/{template_name}.phtml` so it resolves
  through theme overrides and Hyvä compatibility modules.
- **Every parameter arrives as a string.** Widget instances inject parameters through a
  generated layout update (`<action method="setData">`), directives pass them as attribute
  strings, and multiselects arrive comma-joined. The block owns **typed accessors** with
  defaults and coercion (`getTitle(): string`, `getItemsCount(): int`,
  `isShowTitle(): bool`); templates never read raw `getData()`.
- **Parameter-aware cache key.** Override `getCacheKeyInfo()` to append every parameter
  value to `parent::getCacheKeyInfo()`. Block-HTML caching only activates when
  `cache_lifetime` is set, but a widget that forgets this serves one instance's cached
  fragment for every other instance the moment someone enables it.
- **No business logic in the block.** Data loading (products, CMS entities, API calls)
  belongs in a constructor-injected service or ViewModel the block delegates to. Tests mock
  the delegate. A widget that renders persisted entities also implements
  `Magento\Framework\DataObject\IdentityInterface` so full-page cache invalidates on save.
- **Theme-neutral template.** Plain PHP + semantic HTML, `$escaper` on every output, no
  jQuery / Knockout / RequireJS / `data-mage-init` assumptions — the same file renders under
  Luma, Hyvä (Tailwind classes need the module registered for scanning), and Breeze.
  JS behaviour is a separate task for `frontend` or `breeze-adapt`.
- **`<containers>` ↔ `template` parameter contract.** Each `<container>/<template value>`
  must equal an `<option name>` of the `template` select parameter; otherwise that
  container offers no template in the widget-instance form. Omit `<containers>` entirely
  to allow every layout container.
- **Selects need a source.** `select` / `multiselect` parameters declare either inline
  `<options>` (`selected="true"` = the form default — the scaffold's Yes/No `show_title`
  works this way and needs no extra module) or `source_model="..."` (an
  `OptionSourceInterface`; no declarable default, and a source from another module —
  `Magento\Config\Model\Config\Source\Yesno` is `Magento_Config`'s — is a dependency to
  declare like any other). `<value>` on a `text` parameter is its form default.
- **Declare every dependency.** `etc/module.xml` gains
  `<sequence><module name="Magento_Widget"/></sequence>` and `composer.json` gains a
  **bounded** `magento/module-widget` requirement; every other module whose class
  `widget.xml` names (a source model, a chooser block, `Magento_CatalogWidget` for
  `conditions`) is declared the same way. Widget declarations are read from the merged
  `widget.xml` config, so after any edit run
  `{ctx.magento_cli} cache:clean config block_html full_page layout`; a changed sequence
  additionally needs `{ctx.magento_cli} setup:upgrade`.
- **Email compatibility is opt-in.** `is_email_compatible="true"` lists the widget in the
  email-template editor; such widgets must emit inline-styled, JS-free HTML with absolute
  URLs. Default is `false`.
- **PHPCS / coding style.** Generated PHP follows PER-CS 3.0 as the baseline with the
  Magento 2 coding standard taking precedence; `--standard=Magento2` is the gate.
  `declare(strict_types=1)` on every file; no `final` on any class.
  See `context/references/php-coding-style.md`.
- **Source of truth.** Generate from templates → shared references → baked-in Magento 2 knowledge
  → official Magento/Adobe docs (live-fetched only when uncertain). Do NOT read, grep, or "study"
  other modules under `app/code`/`vendor/*`/Magento core to infer conventions, entity shapes,
  naming, or wiring. Narrow exceptions: the target module/class of this operation, and the specific
  contract of a module this code explicitly depends on. Affirm sources in the final report. See
  `context/references/source-of-truth.md`.
- **After a context compaction,** re-read the reference for the phase in progress before continuing.

## Workflow

### Phase 0 — Context Resolution

Invoke `context` (or run
`${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/resolve-context.sh`); capture the
JSON as `{ctx}`. Abort if `{ctx.magento_root}` is unresolved.

**Hard stop if the target module does not exist.** Check
`{ctx.magento_root}/app/code/{Vendor}/{Module}/registration.php`. If absent, offer
`module-create` and abort — do not scaffold into a non-existent module.

Read `{ctx.theme.frontend}` and `{ctx.theme.breeze}` for the theme notes in Phase 5. They
do not change what is generated — the template is theme-neutral — but they change the
follow-up advice (Hyvä Tailwind registration, Breeze JS routing). A `null` theme is
reported as "active theme unknown", never assumed to be Luma. Note `{ctx.magento_version}`
for the integration-test attribute choice in Phase 3.

### Phase 1 — Resolve Inputs

Ask for any missing values in one batch. The flags in **Inputs** cover identity only;
parameters, containers and the data source are collected conversationally.

| Input | Default | Notes |
|-------|---------|-------|
| Module | (ask) | Existing `{Vendor}_{Module}` |
| Widget class name | (ask) | PascalCase, e.g. `PromoBanner`; placed in `Block/Widget/` |
| Widget id | derived | `{vendor_lower}_{module_lower}_{widget}` per the Core Rule, e.g. `acme_promo_banner`; `--id` overrides |
| Widget label | (ask) | Shown in the admin widget-type dropdown and WYSIWYG insert dialog |
| Widget description | (ask) | One sentence, shown next to the label in admin |
| Parameters | template set | Per parameter: name, `xsi:type` (`text` / `select` / `multiselect` / `block` / `conditions`), label, required, default, `<options>` or `source_model`, `depends`. The template ships `title` (text, required), `show_title` (inline Yes/No select, default Yes), `items_count` (text, default 5), `template` (select) — extend or replace |
| Template file name | derived | snake_case of the class name (`PromoBanner` → `promo_banner`) → `view/frontend/templates/widget/{template_name}.phtml` |
| Containers | `content`, `sidebar.main`, `sidebar.additional` | Restricts placement in the widget-instance form; say "unrestricted" to omit `<containers>` |
| Email compatible | `false` | `true` only for JS-free, inline-styled output |
| Placeholder image | none | Optional `{Vendor}_{Module}::images/widget/{widget_id}.png` shown in the WYSIWYG editor; the default Magento placeholder is used when absent |
| Data source | none | Optional service / repository the block delegates to; when set, the block also implements `IdentityInterface` |

See `${CLAUDE_SKILL_DIR}/references/widget-anatomy.md` and
`${CLAUDE_SKILL_DIR}/references/parameter-types.md`.

### Phase 2 — Plan

Present every file to create or modify. Typical file set:

- `etc/widget.xml` (merge)
- `etc/module.xml` (merge — `Magento_Widget` sequence, plus any borrowed module)
- `composer.json` (merge — bounded `magento/module-widget` requirement, plus any borrowed module)
- `Block/Widget/{WidgetName}.php`
- `view/frontend/templates/widget/{template_name}.phtml`
- `Test/Unit/Block/Widget/{WidgetName}Test.php`
- `Test/Integration/Widget/{WidgetName}DeclarationTest.php`

Wait for "proceed."

### Phase 3 — Test First, then Generate

**RED first (3A):** write the unit + declaration-integration tests, scaffold only the block's signature with every accessor and `getCacheKeyInfo()` throwing `not implemented`, and confirm the behaviour tests fail on that exception. **GREEN (3B):** fill in the real bodies and write `widget.xml`, `module.xml`, the template; keep every `<parameter name>` in lockstep across `widget.xml`, the block accessor, and the unit test. Never report an integration test as passed when it could not run.
**Read `references/phase3-generate.md` before starting this phase.**

### Phase 4 — Verify

- `php -l` on every generated `.php` and `.phtml` file.
- `xmllint --noout` on every generated `.xml` file — well-formedness only. When
  `{ctx.magento_root}/vendor/magento/module-widget/etc/widget.xsd` exists, also validate
  `etc/widget.xml` against it with the XML-catalog recipe in
  `${CLAUDE_SKILL_DIR}/references/widget-anatomy.md` (a misspelled attribute passes
  `--noout` and fails only there or at runtime).
- Run the Phase 3A unit test again and confirm it now **passes** (it failed before 3B);
  run the integration test where the framework is available; run the module suite to
  confirm nothing else broke.
- **Apply the shared module-hygiene baseline (required).** After generating or modifying
  PHP files, run
  `${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/add-license-headers.sh {ctx.magento_root}/app/code/{Vendor}/{Module} {Vendor}`
  to stamp the standard copyright header onto every new `.php` (idempotent — it skips files
  that already carry it). When adding a `composer.json` `require` entry, resolve a
  **bounded** constraint via
  `${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/resolve-dep-constraint.sh magento/module-widget` —
  never `"*"`. See `context/references/module-hygiene.md`.
- Run `review --diff` (gate: zero Critical/High findings).
- Consult `${CLAUDE_SKILL_DIR}/references/pitfalls.md` before declaring Phase 4 done.

### Phase 5 — Report

Write a brief Markdown report to
`{output_root}/widgets/{Vendor}_{Module}-{widget_id}-{date}.md` listing:

- Widget id, label, block FQCN, and the parameter table (name / type / default)
- Files generated
- Test path + red→green evidence (and any honestly skipped integration test)
- Activation: `{ctx.magento_cli} setup:upgrade` (sequence change) then
  `{ctx.magento_cli} cache:clean config block_html full_page layout` — when
  `{ctx.magento_cli}` is null, print `bin/magento` and say the CLI was not resolved
- The three placement paths — **Content → Widgets → Add Widget** (type = the label),
  the WYSIWYG *Insert Widget* button, and the directive form
  `{{widget type="{Vendor}\{Module}\Block\Widget\{WidgetName}" title="..." items_count="5"}}`
  — plus the layout-XML `<block class="..." template="...">` form for developers
- Theme notes: Hyvä → register the module for Tailwind scanning if the template uses
  utility classes; Breeze active → any JS behaviour goes through `breeze-adapt`;
  `theme.frontend` null → "active theme unknown"
- Sources affirmed (templates / references / official docs fetched, if any)

> **Docs may now be stale.** This change modified module code. Run
> `docs --module={Vendor}_{Module}` to refresh the module's README,
> CHANGELOG, and `docs/*.md` (technical reference, guides, and API references as
> applicable).

## Inputs

```
/widget --module=Acme_Promo --class=PromoBanner \
  --label="Promo Banner" --description="Configurable promotional banner" \
  [--id=acme_promo_banner] [--containers=content,sidebar.main] \
  [--email-compatible] [--placeholder-image=Acme_Promo::images/widget/banner.png] \
  [--docs-root=<path>]
```

`--docs-root=<path>` — output-root override; see "Output root" below. Parameters beyond
the template set are collected conversationally in Phase 1.

## Outputs

```
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/widget.xml                                  (merge)
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/module.xml                                  (merge)
{ctx.magento_root}/app/code/{Vendor}/{Module}/composer.json                                   (merge)
{ctx.magento_root}/app/code/{Vendor}/{Module}/Block/Widget/{WidgetName}.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/view/frontend/templates/widget/{template_name}.phtml
{ctx.magento_root}/app/code/{Vendor}/{Module}/Test/Unit/Block/Widget/{WidgetName}Test.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Test/Integration/Widget/{WidgetName}DeclarationTest.php

{output_root}/widgets/{Vendor}_{Module}-{widget_id}-{date}.md
```

`{output_root}` defaults to `.docs` (`{ctx.docs_root}`), anchored at the project root, never
under `{ctx.magento_root}`, `app/code`, or a module dir. See the **Artifact location** rule in
`context/SKILL.md`.

### Output root (`--docs-root`)

This skill accepts `--docs-root=<path>` (see
`context/references/artifact-layout.md`). When set, write the run report (and any
report artifacts) under `<path>/widgets/`; otherwise default to
`{ctx.docs_root}/widgets/`. `feature` passes this so a feature run's
reports collect under its folder.

## Reference Files

| Reference | Read when |
|---|---|
| `${CLAUDE_SKILL_DIR}/references/phase3-generate.md` | Phase 3 (tests, then generate) |
| `${CLAUDE_SKILL_DIR}/references/widget-anatomy.md` | `widget.xml` structure, parameter delivery, container/template contract, cache-clean + schema validation |
| `${CLAUDE_SKILL_DIR}/references/parameter-types.md` | choosing parameter `xsi:type`, options vs `source_model`, defaults, `depends` |
| `${CLAUDE_SKILL_DIR}/references/pitfalls.md` | Phases 3–4 (generation pitfalls; before declaring Phase 4 done) |
| `context/references/naming.md` | naming conventions |
| `context/references/tdd-discipline.md` | Phase 3 RED/GREEN loop and integration-test fallback |
| `context/references/php-coding-style.md` | PER-CS + Magento coding style |
| `context/references/placeholder-schema.md` | token registry |
| `context/references/theme-detection.md` | `theme.frontend` / `theme.breeze` resolution (`null` is not Luma) |

- `context/references/source-of-truth.md` — source-of-truth hierarchy + the no-unrelated-module-scanning rule.

## Templates

- `templates/widget.xml` → `etc/widget.xml` (merge)
- `templates/module.xml` → `etc/module.xml` (merge — sequence only)
- `templates/widget-block.php` → `Block/Widget/{WidgetName}.php`
- `templates/widget-template.phtml` → `view/frontend/templates/widget/{template_name}.phtml`
- `templates/test-widget-block-unit.php` → `Test/Unit/Block/Widget/{WidgetName}Test.php`
- `templates/test-widget-declaration-integration.php` →
  `Test/Integration/Widget/{WidgetName}DeclarationTest.php`

All templates follow the placeholder registry in
`context/references/placeholder-schema.md`. Every token used must be in the
registry — `tests/test-placeholder-tokens.sh` enforces it.

## Acceptance Criteria

- All generated files pass `php -l` / `xmllint --noout`; `etc/widget.xml` validates
  against `widget.xsd` where a Magento root is available.
- Widget id follows `{vendor_lower}_{module_lower}_{widget}` — the vendor + module prefix
  is what rules out collisions; the integration test's class-type assertion would expose
  one anyway.
- `etc/module.xml` sequences `Magento_Widget` (and every module whose class `widget.xml`
  names); `composer.json` requires them with bounded constraints.
- The block extends `Template`, implements `BlockInterface`, sets a fully-qualified
  `$_template`, exposes one typed accessor per parameter (except `template`), and
  overrides `getCacheKeyInfo()` with every parameter value.
- Every `<container>/<template value>` matches an `<option name>` of the `template`
  parameter; every `select` / `multiselect` has `<options>` or `source_model`.
- The template escapes every output via `$escaper`, reads only typed accessors, and
  contains no jQuery / Knockout / RequireJS / `data-mage-init` markup.
- Unit test asserts defaults, coercion, and cache-key variance per parameter with real
  assertions and was watched to fail on the throwing stub first; integration test asserts
  the merged widget config and a frontend render (or is skipped with the exact reason
  recorded in the report).
- `review --diff` returns zero Critical/High findings.

## Related Skills

| Phase | Skill |
|-------|-------|
| 0 | `context` |
| Before (if module absent) | `module-create` |
| After | `review --diff` |
| JS behaviour for the widget (RequireJS / Knockout / Alpine) | `frontend` |
| Breeze-active store needing JS | `breeze-adapt` (scope with `breeze-compat` first) |
| Admin-configurable defaults for the widget | `system-config` |
Files in this package (11)
  • SKILL.md 18 KB
  • references/parameter-types.md 7 KB
  • references/phase3-generate.md 4 KB
  • references/pitfalls.md 8 KB
  • references/widget-anatomy.md 10 KB
  • templates/module.xml 1 KB
  • templates/test-widget-block-unit.php 6 KB
  • templates/test-widget-declaration-integration.php 3 KB
  • templates/widget-block.php 3 KB
  • templates/widget-template.phtml 1 KB
  • templates/widget.xml 4 KB

Versions

RepositoryScoreLicence
This page · muon-m2/magento2-tools100MIT
LeoYeAI/openclaw-master-skills100MIT

Database snapshot: 13.11.2026 · package version b922731a16a7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100breeze-adapt
    Adapt an existing Magento 2 module to Swissup Breeze by generating a companion module {Vendor}_{Module}Breeze that converts RequireJS/Knockout/jQuery widgets to Cash `$.widget`. Never edits the target, so it works on vendor/ modules. Use to make a module work with Breeze (needs…
  • 100frontend
    Frontend scaffolding for Magento 2: themes, RequireJS modules, Knockout components, LESS/CSS, transactional email templates, static asset wiring. Use to add frontend behaviour or a theme. Detects Luma, Hyva, or a custom theme and generates matching scaffolds. For Swissup Breeze…
  • 100magento-frontend
    Build Magento 2 frontend — layout XML, blocks, PHTML templates, ViewModels, themes, JavaScript (RequireJS/KnockoutJS), and LESS/CSS. Use when customizing the storefront, building themes, or working with frontend components.
  • 100magento-hyva
    Hyvä theme development for Magento 2 / Mage-OS / Adobe Commerce: building and customizing Hyvä storefronts with Alpine.js and Tailwind CSS, Magewire reactive server-driven components, child-theme setup and the Tailwind build, overriding Hyvä/Luma templates and layout XML, and…
  • 100add-widget
    Step-by-step house pattern for adding an interactive widget to a module — the React component built from the widget-shell kit, the `show_*` widget tool, the app-only `*_data` feed, and the four-link registration chain. Use whenever adding or changing widgets, `show_*` tools,…
  • 100pythonide-widget
    Create or repair PythonIDE iOS Home Screen widgets using widget.Widget(), widget.param, widget.state, charts, tables, canvas layouts, and family branching. Use when the user asks for a WidgetKit widget, desktop widget script, or widget preview — not an AppUI MiniApp.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.