admin-listing
/admin-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. Pairs with magento2-tools:admin-form (the edit form); for the form itself use magento2-tools:admin-form. Detects edition and flags Commerce-only grid features.
- Author
- muon-m2 ↗
- Repository
- magento2-tools ↗
- Licence
- MIT
- Last repository change
- 04.10.2026
Assessment and security
- Files in this package
- 23
- Scripts
- 7
- 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.
- 7 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/verify-listing.sh, templates/column-actions.php, templates/controller-index.php, templates/controller-mass-delete.php, templates/controller-mass-status.php, templates/data-provider.php, templates/grid-collection.php
What it does and when to use it
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. Pairs with magento2-tools:admin-form (the edit form); for the form itself use magento2-tools:admin-form. Detects edition and flags Commerce-only grid features.
Original author description
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. Pairs with magento2-tools:admin-form (the edit form); for the form itself use magento2-tools:admin-form. Detects edition and flags Commerce-only grid features.
How it works
- Core Rules
- Workflow
- Inputs
- Outputs
- Reference Files
- Templates
- Acceptance Criteria
- Common Pitfalls Handled
- Related Skills
SKILL.md preview
---
name: admin-listing
version: 1.1.3
description: >-
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. Pairs with
magento2-tools:admin-form (the edit form); for the form itself use magento2-tools:admin-form.
Detects edition and flags Commerce-only grid features.
---
# Magento 2 Adminhtml Listing
Scaffold a backend entity **grid/listing** the modern way — a declarative
`view/adminhtml/ui_component/{entity}_listing.xml` bound to a `DataProvider`, with an actions
column, mass-action controllers, and an `Index` controller — optionally wired to a sibling edit
form. Never the legacy `Magento\Backend\Block\Widget\Grid`.
## Core Rules
- **Declarative UI component only.** The listing is XML (`ui_component/{entity}_listing.xml`) + a
PHP `DataProvider`. Never generate `Block\Widget\Grid` / `Block\Widget\Grid\Container`.
- **The naming contract prevents the empty grid.** These five names MUST agree, or the grid
renders empty with no error:
1. file name → `{vendor_lower}_{module_lower}_{entity}_listing.xml`
2. `js_config` → `provider` → `{LISTING}.{SOURCE}` where `LISTING={vendor_lower}_{module_lower}_{entity}_listing` and `SOURCE={LISTING}_data_source`
3. `<settings>` → `<deps>` → `<dep>` → `{LISTING}.{SOURCE}`
4. `<dataSource name>` and inner `<dataProvider name>` → both `{SOURCE}`
5. `<columns name>` → `{vendor_lower}_{module_lower}_{entity}_columns` (referenced by `<spinner>`)
- **Default DataProvider is `AbstractDataProvider` + `CollectionFactory`.** `AbstractDataProvider::getData()` already returns the grid shape (`['items' => [...], 'totalRecords' => N]`) — do NOT override `getData()`. Inject `CollectionFactory` and assign `$this->collection`. See `references/dataprovider-wiring.md`.
- **Optional SearchResult path.** For joins or large grids, swap the PHP DataProvider for the generic `Magento\Framework\View\Element\UiComponent\DataProvider\DataProvider` plus a `di.xml` `CollectionFactory.collections` map pointing to `Grid\Collection extends SearchResult`. The `di-listing.xml` template handles this. See `references/dataprovider-wiring.md` and `references/grid-collection.md`.
- **`selectionsColumn` is required for mass actions.** Without `<selectionsColumn name="ids">`, the mass-action checkboxes never appear and mass actions are silently inert.
- **`actionsColumn` must carry the correct `indexField`.** The `indexField` setting in `<actionsColumn>` must match the primary key column (e.g. `faq_id` for `faq`). A mismatch produces blank or broken edit/delete URLs.
- **Reuse the form's acl/menu/routes when present.** If `admin-form` already created `etc/adminhtml/routes.xml`, `etc/acl.xml`, and `etc/adminhtml/menu.xml` for the same module, do not overwrite them — merge only the listing's ACL resource if absent. Create them when the listing is standalone. **When reusing, the listing's own generated artifacts must reference the FORM's route-id (`{vendor_lower}_{entity}`) and ACL resource (`{Vendor}_{ModuleName}::{entity}`)** — in the `Index`/mass-action controllers' `ADMIN_RESOURCE`, the `<aclResource>` in `{entity}_listing.xml`, the layout handle, the menu `action`/`resource`, and the actions-column Edit/Delete/Add-New URLs — **not** this skill's standalone `{vendor_lower}_{module_lower}` / `::main` defaults, which would not match what the form created (an admin route-404 / access-denied on Edit and Delete). The two skills must resolve to one route-id and one base ACL resource for the same module.
- **Layout uses `admin-1column`.** The listing layout (`layout-index.xml`) must declare `layout="admin-1column"` — a full-width grid. `admin-2columns-left` leaves an empty left column.
- **Never assume a running Magento instance.** Generate files; do not call `bin/magento` or hit the database during generation. `setup:upgrade` is a post-gen command listed in the Phase 5 report.
- **Edition awareness.** Detect `{ctx.edition}`. A basic grid is Open Source-compatible. Flag Commerce-only features (e.g. advanced column types, staging) and gate them. See `references/edition-differences.md`.
- **Test-first.** Write the failing test before the listing 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 `{EntityName}` + lowercase `{entity}` (e.g. `Faq`/`faq`) |
| Primary key column | `{entity}_id` | The id column referenced by `selectionsColumn` and `actionsColumn`; matches the paired form's `getParam('{entity}_id')` |
| Columns | (ask) | Each: name, label, column type, filter type, sortOrder |
| Has status field? | (ask) | Enables MassStatus controller + enable/disable mass actions |
| Paired form? | (ask) | Name of the edit form (used for actions column routes); "none" if standalone |
| Performance path? | No | Use `SearchResult` + `di` map when joins / large tables are needed |
| ACL resource | `{Vendor}_{Module}::main` | Guards Index + mass controllers |
Consult `references/columns-and-types.md`, `references/edition-differences.md` while asking.
### Phase 2 — Plan
Present the file plan (every path to create/modify, surfaces enabled, ACL/route/menu touches,
DataProvider wiring chosen). Wait for "proceed."
### Phase 3 — Test First, then Generate
**3A — Write the failing test (RED).** Before any listing code, add a test under `Test/Integration/`
that boots the `DataProvider` and asserts `getData()` returns the grid shape
(`['items' => [...], 'totalRecords' => N]`), plus a controller test (Index returns HTTP 200 and
the correct page title; MassDelete processes the correct collection). If no test DB is available,
fall back to a unit test of the DataProvider construction 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`.
**3B — Generate (GREEN).** Write the minimal files from `templates/` to turn 3A green:
- `templates/listing.xml` → `view/adminhtml/ui_component/{vendor_lower}_{module_lower}_{entity}_listing.xml`
- `templates/data-provider.php` → `Ui/DataProvider/{EntityName}DataProvider.php`
- `templates/column-actions.php` → `Ui/Component/Listing/Column/{EntityName}Actions.php`
- `templates/controller-index.php` → `Controller/Adminhtml/{EntityName}/Index.php`
- `templates/controller-mass-delete.php` → `Controller/Adminhtml/{EntityName}/MassDelete.php`
- `templates/controller-mass-status.php` → `Controller/Adminhtml/{EntityName}/MassStatus.php` (when status surface enabled)
- `templates/layout-index.xml` → `view/adminhtml/layout/{vendor_lower}_{module_lower}_{entity}_index.xml`
- `templates/routes.xml`, `acl.xml`, `menu.xml` (created-if-absent / merged-from-form)
- Optional: `templates/di-listing.xml` + `templates/grid-collection.php` (SearchResult path)
### Phase 4 — Verify
- `xmllint --noout` on every XML (`{ctx.tools.xmllint}`): listing, 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 empty-grid 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-listing.sh` runs the XML + PHP lints in one pass.
### Phase 5 — Report
Brief Markdown saved to `{output_root}/adminhtml-listings/{Vendor}_{Module}-{entity}-listing-{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 listing'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-listing --module=Acme_Faq --entity=Faq --primary=faq_id --status --paired-form=acme_faq_faq [--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/{vendor_lower}_{module_lower}_{entity}_listing.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/Ui/DataProvider/{EntityName}DataProvider.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Ui/Component/Listing/Column/{EntityName}Actions.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Controller/Adminhtml/{EntityName}/Index.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Controller/Adminhtml/{EntityName}/MassDelete.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Controller/Adminhtml/{EntityName}/MassStatus.php # status surface
{ctx.magento_root}/app/code/{Vendor}/{Module}/view/adminhtml/layout/{vendor_lower}_{module_lower}_{entity}_index.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/adminhtml/{routes,menu}.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/acl.xml
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/di.xml # optional: SearchResult path
{ctx.magento_root}/app/code/{Vendor}/{Module}/Model/ResourceModel/{EntityName}/Grid/Collection.php # optional
{ctx.magento_root}/app/code/{Vendor}/{Module}/Test/Integration/.../{EntityName}ListingTest.php # test-first
{output_root}/adminhtml-listings/{Vendor}_{Module}-{entity}-listing-{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-listings/`; otherwise default to
`{ctx.docs_root}/adminhtml-listings/`. `feature` passes this so a
feature run's reports collect under its folder.
## Reference Files
- `references/listing-xml-anatomy.md` — `{entity}_listing.xml` structure + the 5-place naming contract.
- `references/dataprovider-wiring.md` — default `AbstractDataProvider` path vs optional `SearchResult`+di path.
- `references/columns-and-types.md` — text/select/date/actionsColumn, filters, options sources, sortOrder.
- `references/mass-actions.md` — selectionsColumn + massaction + MassDelete/MassStatus controllers + Filter pattern.
- `references/grid-collection.md` — SearchResult collection (joins, mainTable/resourceModel, `_initSelect`).
- `references/controllers-and-routing.md` — Index + mass controllers, ADMIN_RESOURCE, routes, layout handles.
- `references/edition-differences.md` — Open Source vs Adobe Commerce grid notes.
- `references/pairing-with-form.md` — actions column / Add-New button targeting the form's routes; reusing acl/menu/routes; `admin-1column` layout.
- `references/pitfalls.md` — empty grid, inert mass actions, broken actionsColumn, wrong layout handle.
- `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/listing.xml`
- `templates/data-provider.php`
- `templates/column-actions.php`
- `templates/controller-index.php`
- `templates/controller-mass-delete.php`
- `templates/controller-mass-status.php`
- `templates/layout-index.xml`
- `templates/routes.xml`, `templates/acl.xml`, `templates/menu.xml`
- `templates/di-listing.xml` (optional: SearchResult path)
- `templates/grid-collection.php` (optional: SearchResult path)
All templates follow the placeholder registry in
`context/references/placeholder-schema.md` using the `{Vendor}` / `{ModuleName}` /
`{EntityName}` / `{entity}` / `{vendor_lower}` / `{module_lower}` convention. Every token used
must be registered there — `tests/test-placeholder-tokens.sh` enforces it.
## Acceptance Criteria
- The five naming-contract names agree; the grid loads rows and paginates.
- `selectionsColumn` present and `actionsColumn` carries the correct `indexField`.
- DataProvider returns the grid shape without overriding `getData()`.
- `acl.xml` has no `translate` attribute; every XML passes `xmllint --noout`.
- A test asserting DataProvider construction + grid shape **and** the Index controller render was written and **watched to fail** before the listing 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 |
|---------|--------------------------|
| Empty grid | The five-name naming contract is generated consistently |
| Mass actions inert | `selectionsColumn` always generated before any `<massaction>` element |
| Broken edit/delete URLs | `actionsColumn indexField` matches the primary key column |
| Wrong layout (empty left column) | `admin-1column` declared in `layout-index.xml` |
| DataProvider returns wrong shape | `AbstractDataProvider::getData()` not overridden — grid shape by default |
| `xmllint` fails on acl.xml | No `translate` attribute on `<resource>` |
| Empty grid on SearchResult path | `di.xml` collections map key matches `{SOURCE}` name byte-for-byte |
| Commerce-only features on Open Source | Edition checked in Phase 1; advanced features gated |
| Legacy `Block\Widget\Grid` | Skill refuses; declarative UI component only |
## Related Skills
| Phase | Skill |
|-------|-------|
| 0 | `context` |
| upstream | `module-create` — create the module first if absent; defers here for standalone grids |
| sibling | `admin-form` — the edit form this listing's actions column links to |
| downstream | `test-generate` — fuller unit/integration/MFTF coverage |
| gate | `review` — acceptance gate (zero Critical/High) |
| (caller) | `feature` — the admin-listing slice of a feature |
Files in this package (23)
- SKILL.md 16 KB
- references/columns-and-types.md 4 KB
- references/controllers-and-routing.md 4 KB
- references/dataprovider-wiring.md 4 KB
- references/edition-differences.md 2 KB
- references/grid-collection.md 4 KB
- references/listing-xml-anatomy.md 4 KB
- references/mass-actions.md 6 KB
- references/pairing-with-form.md 3 KB
- references/pitfalls.md 3 KB
- scripts/verify-listing.sh 2 KB
- templates/acl.xml 1 KB
- templates/column-actions.php 2 KB
- templates/controller-index.php 1 KB
- templates/controller-mass-delete.php 2 KB
- templates/controller-mass-status.php 2 KB
- templates/data-provider.php 1 KB
- templates/di-listing.xml 1 KB
- templates/grid-collection.php 1 KB
- templates/layout-index.xml 1 KB
- templates/listing.xml 5 KB
- templates/menu.xml 1 KB
- templates/routes.xml 1 KB
Versions
The database has no other skills named admin-listing.
Database snapshot: 13.11.2026 · package version 48b4c371bf73 (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-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,… - 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… - 86admin-add-field
Use when adding a column or field to an existing admin module (new input on the form, new list column, new attribute on the model). - 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'… - 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. - 100orchardcore-admin-index-views
Builds OrchardCore admin index (list) pages with the AdminList shape and the admin-list tag helpers — view-declared columns, row display drivers placing shapes for both the SummaryAdmin (List) and SummaryAdminGrid (Grid) display types, column providers, row actions, toolbar,…