Skip to content
Skills Library
Programming · Building & coding

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.

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
29
Scripts
12
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
  • 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

  1. Core Rules
  2. Workflow
  3. Inputs
  4. Outputs
  5. Reference Files
  6. Templates
  7. Acceptance Criteria
  8. Common Pitfalls Handled
  9. Related Skills
Original SKILL.md headings · 235 lines, 1,580 words
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…

Feedback and reports

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