admin-listing
/admin-listing
Generuje listing lub siatkę adminhtml w Magento 2 jako komponent UI: ui_component/{entity}_listing.xml, DataProvider, kolumny, kolumnę akcji i akcje masowe, podpięte do istniejącego formularza edycji.
- Autor
- muon-m2 ↗
- Repozytorium
- magento2-tools ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 04.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 23
- Skrypty
- 7
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 04.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 7 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: 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
Co robi i kiedy
Generuje listing lub siatkę adminhtml w Magento 2 jako komponent UI: ui_component/{entity}_listing.xml, DataProvider, kolumny, kolumnę akcji i akcje masowe, podpięte do istniejącego formularza edycji.
Oryginalny opis (EN)
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.
Jak działa
- Core Rules
- Workflow
- Inputs
- Outputs
- Reference Files
- Templates
- Acceptance Criteria
- Common Pitfalls Handled
- Related Skills
Podgląd SKILL.md
---
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 |
Pliki w paczce (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
Wersje
W bazie nie ma innych skilli o nazwie admin-listing.
Migawka bazy z 13.11.2026 · wersja paczki 48b4c371bf73 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100admin-form
Generuje formularz edycji adminhtml w Magento 2 jako komponent UI: ui_component/{entity}_form.xml, DataProvider, przyciski oraz kontrolery New, Edit, Save i Delete podpięte do listingu. - 100commerce-app-admin-ui
Dodaje lub zmienia rozszerzenia Admin UI Adobe Commerce na punkcie commerce/backend-ui/2: kolumny siatek, akcje masowe, przyciski widoku zamówienia, pozycje menu i zasoby ACL. - 86admin-add-field
Dodaje kolumnę lub pole do istniejącego modułu admina: nowe pole formularza, kolumnę listy lub atrybut modelu. - 100system-config
Dodaje do modułu Magento pola konfiguracji w panelu administratora: system.xml, domyślne wartości w config.xml, ACL i typowany odczyt ustawień. - 100magento-admin-ui
Buduje interfejsy administracyjne Magento 2: siatki komponentów UI, formularze, konfigurację systemu, ACL i kontrolery admina, przy tworzeniu paneli, siatek danych i formularzy edycji. - 100orchardcore-admin-index-views
Buduje strony indeksu (listy) panelu administracyjnego OrchardCore z kształtem AdminList i tag helperami: kolumny, sterowniki wyświetlania wierszy dla List i Grid, akcje wierszy, pasek narzędzi, wyszukiwanie i paginacja.