admin-form
/admin-form
Generate a Magento 2 adminhtml UI-component edit form: `ui_component/{entity}_form.xml` plus DataProvider, buttons, and New/Edit/Save/Delete controllers wired to a listing. Use to add or scaffold an admin form, entity edit page, backend screen, fieldsets, WYSIWYG field, toggle, dynamic-rows, or file/image uploaders in the Magento admin. Detects edition and flags Commerce-only features. For the grid use magento2-tools:admin-listing.
- Author
- muon-m2 ↗
- Repository
- magento2-tools ↗
- Licence
- MIT
- Last repository change
- 04.10.2026
Assessment and security
- Files in this package
- 29
- Scripts
- 12
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 12 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/verify-form.sh, templates/back-button.php, templates/controller-delete.php, templates/controller-edit.php, templates/controller-new.php, templates/controller-save.php, templates/data-provider.php, templates/delete-button.php, templates/generic-button.php, templates/modifier.php, templates/save-and-continue-button.php, templates/save-button.php
What it does and when to use it
Generate a Magento 2 adminhtml UI-component edit form: `ui_component/{entity}_form.xml` plus DataProvider, buttons, and New/Edit/Save/Delete controllers wired to a listing. Use to add or scaffold an admin form, entity edit page, backend screen, fieldsets, WYSIWYG field, toggle, dynamic-rows, or file/image uploaders in the Magento admin. Detects edition and flags Commerce-only features. For the grid use magento2-tools:admin-listing.
Original author description
Generate a Magento 2 adminhtml UI-component edit form: `ui_component/{entity}_form.xml` plus DataProvider, buttons, and New/Edit/Save/Delete controllers wired to a listing. Use to add or scaffold an admin form, entity edit page, backend screen, fieldsets, WYSIWYG field, toggle, dynamic-rows, or file/image uploaders in the Magento admin. Detects edition and flags Commerce-only features. For the grid use magento2-tools:admin-listing.
How it works
- Core Rules
- Workflow
- Inputs
- Outputs
- Reference Files
- Templates
- Acceptance Criteria
- Common Pitfalls Handled
- Related Skills
SKILL.md preview
---
name: admin-form
version: 1.1.2
description: >-
Generate a Magento 2 adminhtml UI-component edit form: `ui_component/{entity}_form.xml` plus
DataProvider, buttons, and New/Edit/Save/Delete controllers wired to a listing. Use to add or
scaffold an admin form, entity edit page, backend screen, fieldsets, WYSIWYG field, toggle,
dynamic-rows, or file/image uploaders in the Magento admin. Detects edition and flags
Commerce-only features. For the grid use magento2-tools:admin-listing.
---
# Magento 2 Adminhtml Form
Scaffold a backend entity **edit form** the modern way — a declarative
`view/adminhtml/ui_component/{entity}_form.xml` bound to a `DataProvider`, with button
blocks and `New`/`Edit`/`Save`/`Delete` controllers — wired to an existing listing grid.
Never the legacy `Magento\Backend\Block\Widget\Form`.
## Core Rules
- **Declarative UI component only.** The form is XML (`ui_component/{entity}_form.xml`) + a
PHP `DataProvider`. Never generate `Block\Widget\Form` / `Block\Widget\Form\Container`.
- **The naming contract prevents the blank form.** These five names MUST agree, or the form
renders empty with no error:
1. form `<namespace>` and file name → `{entity}_form`
2. `provider` in `js_config` → `{entity}_form.{entity}_form_data_source`
3. `<dataSource name>` and `<dataProvider name>` → `{entity}_form_data_source`
4. layout `<uiComponent name>` → `{entity}_form`
5. layout handle file → `<route_id>_<controller>_edit.xml` (route id + controller path + action)
- **Button blocks are required.** The `<buttons>` in the form reference PHP block classes; the
page errors if they are missing. Always emit `GenericButton` + `Back`, `Save`, `Delete`
(and `SaveAndContinue` when save-and-continue is requested).
- **DataProvider shape is exact.** Extend `Magento\Ui\DataProvider\AbstractDataProvider`
(modifier-less default) or `Magento\Ui\DataProvider\ModifierPoolDataProvider` (only when
modifiers are requested). `getData()` returns `[ $id => [field => value, …] ]` — flat fields,
keyed by entity id. Inject `DataPersistorInterface` so a failed save (and the New screen)
repopulates. See `references/dataprovider-patterns.md`.
- **Save reads FLAT post data.** A standard UI form posts fields flat;
`$this->getRequest()->getPostValue()` → `[{entity}_id, …fields]`. Do **not** unwrap a
`data`/`general` key. Normalise empty id to `null` before `repository->save()`.
- **The modifier/Pool is an OPTIONAL surface.** Default to modifier-less for a new simple form.
Generate a `Modifier` + `di-modifier-pool.xml` only when extending an existing form
(product/customer) or building fields dynamically. See `references/modifier-patterns.md`.
- **acl.xml has no `translate` attribute.** `acl.xsd` allows only `id`, `title`, `sortOrder`,
`disabled` on `<resource>`. `menu.xml` *does* allow `translate`. Mixing them fails xmllint.
- **No storefront handles.** The edit layout is just `<referenceContainer name="content"><uiComponent .../></referenceContainer>`. Do not add `<update handle="styles"/>` (storefront-only).
- **Edition awareness.** Detect `{ctx.edition}`. Content-staging tabs and B2B company forms are
**Adobe Commerce only** — never emit staging wiring on Open Source. See
`references/edition-differences.md`.
- **Test-first.** Write the failing test before the form code (red → green) and **watch it fail
for the right reason**. See `context/references/tdd-discipline.md`.
- **Coding style.** Generated PHP follows PER-CS 3.0 baseline, Magento 2 standard taking
precedence; `--standard=Magento2` PHPCS is the gate. 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`.
## Workflow
### Phase 0 — Context Resolution
Invoke `context`. Capture `{ctx}`. Abort with a clear message if the target module
does not exist (offer `module-create`) or if `{ctx.magento_root}` is unresolved.
### Phase 1 — Resolve Inputs
Ask for any missing values:
| Input | Default | Notes |
|-------|---------|-------|
| Target module | (ask) | Existing `{Vendor}_{Module}`; offer `module-create` if absent |
| Entity name | (ask) | PascalCase `{Entity}` + lowercase `{entity}` (e.g. `Faq`/`faq`) |
| Data loading | (ask) | Existing repository/collection for the entity (must exist) |
| Primary field | `{entity}_id` | The id column / request param / redirect key |
| Fields | (ask) | Each: code, label, `formElement`, `dataType`, required?, source options |
| Surfaces | (ask) | modifier? wysiwyg? toggle? dynamicRows? uploader? dependent fields? delete? save-and-continue? menu entry? |
| Listing to return to | (ask) | Name of the grid the Back button / save redirect target (or "none yet") |
| ACL resource | `{Vendor}_{Module}::{entity}` | Guards Save/Delete controllers |
Consult `references/field-types.md`, `references/validation-rules.md`,
`references/edition-differences.md` while asking so offered options match `{ctx.edition}`.
### Phase 2 — Plan
Present the file plan (every path to create/modify, surfaces enabled, ACL/route/menu touches).
Wait for "proceed."
### Phase 3 — Test First, then Generate
**3A — Write the failing test (RED).** Before any form code, add a test under `Test/Integration/`
that boots the `DataProvider` and asserts `getData()` returns the entity shaped as
`[$id => [...]]`, plus a controller test (Save redirects + sets a success message; Edit 404s/
redirects for a missing id, renders for an existing one). If no test DB is available, fall back to
a unit test of any `Modifier::modifyMeta`/`modifyData` and **record the gap** in the Phase 5
report. Run it and confirm it fails for the right reason. See
`context/references/tdd-discipline.md` and
`test-generate/references/integration-patterns.md`.
**3B — Generate (GREEN).** Write the minimal files from `templates/` to turn 3A green:
- `templates/form.xml` → `view/adminhtml/ui_component/{entity}_form.xml`
- `templates/data-provider.php` → `Model/{Entity}/DataProvider.php`
- `templates/controller-new.php`, `controller-edit.php`, `controller-save.php`, `controller-delete.php`
- `templates/generic-button.php` + `back-button.php`, `save-button.php`, `delete-button.php`
(+ `save-and-continue-button.php` when requested)
- `templates/routes.xml`, `acl.xml`, `menu.xml` (as needed), `layout-edit.xml`
- Optional: `templates/modifier.php` + `di-modifier-pool.xml` (modifier surface)
### Phase 4 — Verify
- `xmllint --noout` on every XML (`{ctx.tools.xmllint}`): form, layout, routes, acl, menu, di.
- `php -l` on every PHP file.
- Run the Phase 3A test with `{ctx.runner} vendor/bin/phpunit`; confirm it now **passes**; run
the module suite to confirm no regressions.
- Confirm the five naming-contract names agree (the blank-form check).
- **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). If you add a `composer.json` `require` entry, resolve a **bounded** constraint via
`${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/resolve-dep-constraint.sh <vendor/package>` —
never `"*"`. See `context/references/module-hygiene.md`.
- Optionally run `review` on the module → zero Critical/High.
- `scripts/verify-form.sh` runs the XML + PHP lints in one pass.
### Phase 5 — Report
Brief Markdown saved to `{output_root}/adminhtml-forms/{Vendor}_{Module}-{entity}-form-{date}.md`:
- Files generated/modified + surfaces enabled
- Test path + red→green evidence (or recorded gap)
- Post-gen commands: `bin/magento setup:upgrade` (if di/routes/menu/acl changed), cache flush,
`setup:di:compile` note for production
- The form's admin URL + ACL resource to grant
- Links to `review` and `test-generate`
> **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
```
/admin-form --module=Acme_Faq --entity=Faq --primary=faq_id --wysiwyg=content --listing=acme_faq_listing [--docs-root=<path>]
```
`--docs-root=<path>` — output-root override; see "Output root" below.
## Outputs
```
{ctx.magento_root}/app/code/{Vendor}/{Module}/view/adminhtml/ui_component/{entity}_form.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/Model/{Entity}/DataProvider.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Controller/Adminhtml/{Entity}/{New,Edit,Save,Delete}.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Block/Adminhtml/{Entity}/Edit/*Button.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/view/adminhtml/layout/{vendor_lower}_{entity}_{entity}_edit.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/adminhtml/{routes,menu,di}.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/acl.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/Test/Integration/.../{Entity}FormTest.php # test-first (Phase 3A)
{output_root}/adminhtml-forms/{Vendor}_{Module}-{entity}-form-{date}.md
```
`{output_root}` defaults to `.docs` (`{ctx.docs_root}`), anchored at the project root, never
under `{ctx.magento_root}`. 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>/adminhtml-forms/`; otherwise default to
`{ctx.docs_root}/adminhtml-forms/`. `feature` passes this so a feature
run's reports collect under its folder.
## Reference Files
- `references/form-xml-anatomy.md` — `{entity}_form.xml` structure + the naming contract.
- `references/dataprovider-patterns.md` — DataProvider base classes, `getData()` shape, persistor.
- `references/modifier-patterns.md` — `ModifierInterface` + Pool (optional surface).
- `references/field-types.md` — `formElement`/`dataType` map; toggle, dynamicRows.
- `references/validation-rules.md` — `required-entry`, `validate-number`, custom + server-side.
- `references/dependent-fields.md` — show/hide via `imports`/`exports`, `switcherConfig`.
- `references/controllers-and-routing.md` — controllers, ACL, routes, layout handle derivation.
- `references/uploaders-wysiwyg.md` — image/file uploader controller + WYSIWYG wiring.
- `references/edition-differences.md` — Open Source vs Adobe Commerce (staging, B2B).
- `references/pitfalls.md` — blank-form / silent-save / 404 root causes and fixes.
- `context/references/tdd-discipline.md` — shared test-first loop (Phase 3A).
- `context/references/source-of-truth.md` — source-of-truth hierarchy + the
no-unrelated-module-scanning rule (allowed reads, live-doc fetch protocol, report affirmation).
## Templates
- `templates/form.xml`
- `templates/data-provider.php`
- `templates/controller-new.php`, `controller-edit.php`, `controller-save.php`, `controller-delete.php`
- `templates/generic-button.php`, `back-button.php`, `save-button.php`, `delete-button.php`,
`save-and-continue-button.php`
- `templates/routes.xml`, `acl.xml`, `menu.xml`, `layout-edit.xml`
- `templates/modifier.php`, `di-modifier-pool.xml` (modifier surface)
All templates follow the placeholder registry in
`context/references/placeholder-schema.md` using the `{Vendor}` / `{Module}` /
`{Entity}` / `{entity}` convention. Every token used must be registered there —
`tests/test-placeholder-tokens.sh` enforces it.
## Acceptance Criteria
- The five naming-contract names agree; the form loads existing data and saves it.
- Button block classes exist for every `<button>` referenced by the form.
- DataProvider returns `[$id => [...]]` and injects `DataPersistorInterface`.
- `acl.xml` has no `translate` attribute; every XML passes `xmllint --noout`.
- A test asserting `getData()` shape **and** the Save/Edit controller behaviour was written and
**watched to fail** before the form existed, and passes after (or the gap is recorded).
- No Commerce-only wiring emitted on Open Source.
- Passes `review` with zero Critical/High findings.
## Common Pitfalls Handled
| Pitfall | How the skill avoids it |
|---------|--------------------------|
| Blank form on Edit | The five-name naming contract is generated consistently |
| Save writes empty/garbage rows | Flat `getPostValue()`; empty id normalised to `null` |
| Form errors on load | Button block classes always generated for referenced buttons |
| New-record / failed-save loses input | `DataPersistorInterface` injected into the DataProvider |
| `xmllint` fails on acl.xml | No `translate` attribute on `<resource>` |
| Blank content area | Layout handle derived as `<route_id>_<controller>_edit` |
| WYSIWYG renders as plain textarea | Canonical `formElement="wysiwyg"` + `wysiwygConfigData` |
| Commerce-only features on Open Source | Edition checked in Phase 1; staging/B2B gated |
| Legacy `Block\Widget\Form` | Skill refuses; declarative UI component only |
## Related Skills
| Phase | Skill |
|-------|-------|
| 0 | `context` |
| upstream | `module-create` — create the module first if absent |
| sibling | `eav-attribute` — add an attribute, then expose it on this form |
| downstream | `test-generate` — fuller unit/integration/MFTF coverage |
| gate | `review` — acceptance gate (zero Critical/High) |
| (caller) | `feature` — the admin-form slice of a feature |
Files in this package (29)
- SKILL.md 14 KB
- references/controllers-and-routing.md 3 KB
- references/dataprovider-patterns.md 3 KB
- references/dependent-fields.md 2 KB
- references/edition-differences.md 2 KB
- references/field-types.md 3 KB
- references/form-xml-anatomy.md 3 KB
- references/modifier-patterns.md 3 KB
- references/pitfalls.md 3 KB
- references/uploaders-wysiwyg.md 2 KB
- references/validation-rules.md 1 KB
- scripts/verify-form.sh 2 KB
- templates/acl.xml 1 KB
- templates/back-button.php 1 KB
- templates/controller-delete.php 2 KB
- templates/controller-edit.php 2 KB
- templates/controller-new.php 1 KB
- templates/controller-save.php 4 KB
- templates/data-provider.php 2 KB
- templates/delete-button.php 1 KB
- templates/di-modifier-pool.xml 1 KB
- templates/form.xml 6 KB
- templates/generic-button.php 1 KB
- templates/layout-edit.xml 1 KB
- templates/menu.xml 1 KB
- templates/modifier.php 1 KB
- templates/routes.xml 1 KB
- templates/save-and-continue-button.php 1 KB
- templates/save-button.php 1 KB
Versions
The database has no other skills named admin-form.
Database snapshot: 13.11.2026 · package version 3e9bfedb3dd8 (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
- 100admin-listing
Generate a Magento 2 adminhtml UI-component listing/grid: `ui_component/{entity}_listing.xml` plus DataProvider, columns, actions column, and mass actions, wired to an existing edit form. Use to add or scaffold an admin grid, data grid, listing page, filters, or mass actions.… - 100magento-admin-ui
Build Magento 2 admin interfaces — UI component grids, forms, system configuration, ACL, and admin controllers. Use when creating admin panels, data grids, edit forms, or system settings. - 100system-config
Add admin store configuration to an existing module — system.xml section/group/field, config.xml defaults, ACL, optional source/backend models, plus a typed Config reader (ScopeConfigInterface wrapper with store-aware getters). Use for 'add a config field/toggle/API-key setting'… - 90magento-di
Configure Magento 2 dependency injection — di.xml, types, virtual types, preferences, argument replacement, and Object Manager. Use when wiring dependencies, creating class variations, or configuring module integrations. - 87magento-module
Correct Magento 2 / Mage-OS / Adobe Commerce module development: scaffolding new modules, extending or customizing core behavior (plugin vs observer vs preference decisions), declarative schema and custom tables, product/EAV attributes, dependency injection, checkout/cart/totals… - 100commerce-app-admin-ui
Add or modify Adobe Commerce Admin UI extensions on the commerce/backend-ui/2 extension point: custom grid columns, mass actions, order view buttons, a custom Admin menu entry, and custom ACL resources. Use whenever the user wants to extend the Commerce Admin — add a column to…