Magento 2 Admin UI & System Configuration
Before writing code
Fetch live docs:
- Fetch
https://developer.adobe.com/commerce/php/development/components/add-admin-grid/ for admin grid tutorial
- Fetch
https://developer.adobe.com/commerce/php/tutorials/backend/create-access-control-list-rule/ for ACL tutorial
- Web-search
site:developer.adobe.com commerce php development components ui-components for UI component reference
Admin Grids (UI Component Listings)
How Admin Grids Work
Grids are XML-declared UI components backed by data providers. They render in the browser using KnockoutJS and load data via AJAX.
Grid XML Structure (ui_component)
Located in view/adminhtml/ui_component/<listing_name>.xml:
<listing> root element with data source<dataSource> — data provider class and configuration<listingToolbar> — bookmarks, columns controls, filters, mass actions, paging<columns> — column definitions (type, label, sortable, filterable)<column> — individual column (text, select, date, actions)<actionsColumn> — edit/delete action links
Data Provider
- Extends
Magento\Ui\DataProvider\AbstractDataProvider
- Backed by a collection (resource model collection)
- Provides data array to the grid
Mass Actions
Bulk operations on selected rows:
- Delete, status change, export
- Declared in grid XML under
<massaction>
- Each action maps to a controller
Admin Forms (UI Component Forms)
Located in view/adminhtml/ui_component/<form_name>.xml:
<form> root element<fieldset> groups related fields<field> — input, textarea, select, multiselect, boolean, date, imageUploader, wysiwyg- Data provider loads entity data for editing
- Save controller processes form submission
System Configuration
system.xml
Defines admin config fields at Stores > Settings > Configuration:
<section> — top-level tab<group> — fieldset within a section<field> — individual configuration field- Field types: text, textarea, select, multiselect, obscure (password), image
config.xml
Provides default values for system configuration fields. Path format: section/group/field.
Reading Config Values
$this->scopeConfig->getValue('section/group/field', ScopeInterface::SCOPE_STORE);
Scopes: default, website, store (store view).
ACL (Access Control List)
acl.xml
Defines resource hierarchy:
- Nested
<resource> elements form a permission tree
- Admin users are assigned to roles; roles get resource permissions
Controller ACL
Admin controllers extend Magento\Backend\App\Action:
const ADMIN_RESOURCE = 'Vendor_Module::resource_name';- Framework checks ACL before executing action
Menu Items
Declared in etc/adminhtml/menu.xml:
- Maps to ACL resources
- Defines position in admin sidebar navigation
Admin Controllers
- Extend
Magento\Backend\App\Action
- Route in
etc/adminhtml/routes.xml
- URL:
admin/<frontName>/<controller>/<action>
- Common patterns: Index (list), Edit, Save, Delete, MassDelete, NewAction
Best Practices
- Always create ACL resources for every admin feature
- Use UI component grids over custom HTML grids
- Provide bookmarks and export in grids
- Validate form data server-side (never trust client)
- Use
resultPageFactory for rendering admin pages with proper layout
- Scope config values appropriately (global vs website vs store view)
Fetch the admin grid tutorial, ACL guide, and UI component reference for exact XML schemas and data provider patterns before implementing.
1---2name: magento-admin-ui3description: 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.4---5
6# Magento 2 Admin UI & System Configuration
7
8## Before writing code
9
10**Fetch live docs**:
111. Fetch `https://developer.adobe.com/commerce/php/development/components/add-admin-grid/` for admin grid tutorial
122. Fetch `https://developer.adobe.com/commerce/php/tutorials/backend/create-access-control-list-rule/` for ACL tutorial
133. Web-search `site:developer.adobe.com commerce php development components ui-components` for UI component reference
14
15## Admin Grids (UI Component Listings)
16
17### How Admin Grids Work
18
19Grids are XML-declared UI components backed by data providers. They render in the browser using KnockoutJS and load data via AJAX.
20
21### Grid XML Structure (ui_component)
22
23Located in `view/adminhtml/ui_component/<listing_name>.xml`:
24- `<listing>` root element with data source
25- `<dataSource>` — data provider class and configuration
26- `<listingToolbar>` — bookmarks, columns controls, filters, mass actions, paging
27- `<columns>` — column definitions (type, label, sortable, filterable)
28- `<column>` — individual column (text, select, date, actions)
29- `<actionsColumn>` — edit/delete action links
30
31### Data Provider
32
33- Extends `Magento\Ui\DataProvider\AbstractDataProvider`
34- Backed by a collection (resource model collection)
35- Provides data array to the grid
36
37### Mass Actions
38
39Bulk operations on selected rows:
40- Delete, status change, export
41- Declared in grid XML under `<massaction>`
42- Each action maps to a controller
43
44## Admin Forms (UI Component Forms)
45
46Located in `view/adminhtml/ui_component/<form_name>.xml`:
47- `<form>` root element
48- `<fieldset>` groups related fields
49- `<field>` — input, textarea, select, multiselect, boolean, date, imageUploader, wysiwyg
50- Data provider loads entity data for editing
51- Save controller processes form submission
52
53## System Configuration
54
55### system.xml
56
57Defines admin config fields at Stores > Settings > Configuration:
58- `<section>` — top-level tab
59- `<group>` — fieldset within a section
60- `<field>` — individual configuration field
61- Field types: text, textarea, select, multiselect, obscure (password), image
62
63### config.xml
64
65Provides default values for system configuration fields. Path format: `section/group/field`.
66
67### Reading Config Values
68
69```php
70$this->scopeConfig->getValue('section/group/field', ScopeInterface::SCOPE_STORE);
71```
72
73Scopes: default, website, store (store view).
74
75## ACL (Access Control List)
76
77### acl.xml
78
79Defines resource hierarchy:
80- Nested `<resource>` elements form a permission tree
81- Admin users are assigned to roles; roles get resource permissions
82
83### Controller ACL
84
85Admin controllers extend `Magento\Backend\App\Action`:
86- `const ADMIN_RESOURCE = 'Vendor_Module::resource_name';`
87- Framework checks ACL before executing action
88
89### Menu Items
90
91Declared in `etc/adminhtml/menu.xml`:
92- Maps to ACL resources
93- Defines position in admin sidebar navigation
94
95## Admin Controllers
96
97- Extend `Magento\Backend\App\Action`
98- Route in `etc/adminhtml/routes.xml`
99- URL: `admin/<frontName>/<controller>/<action>`
100- Common patterns: Index (list), Edit, Save, Delete, MassDelete, NewAction
101
102## Best Practices
103
104- Always create ACL resources for every admin feature
105- Use UI component grids over custom HTML grids
106- Provide bookmarks and export in grids
107- Validate form data server-side (never trust client)
108- Use `resultPageFactory` for rendering admin pages with proper layout
109- Scope config values appropriately (global vs website vs store view)
110
111Fetch the admin grid tutorial, ACL guide, and UI component reference for exact XML schemas and data provider patterns before implementing.
majiayu000