Headless Digital 5 min readmagentodev-workflow

Magento 2 admin module development for beginners

The original video this piece is based on.

This is the follow-on to my module development for beginners piece. Once you have a module that registers and renders something, the next two jobs that land on every Magento developer are admin work and proper front end modules. I pulled this together from a run of videos I recorded in 2022 on Magento 2.4.4, so read the class names and paths as the shape of the thing rather than a line to copy blind. The approach is what carries over, and it has held up fine.

Read the brief before you write any code

The admin video started with a real client brief, and the most useful thing in it was not the code. The brief said, roughly, can we add an account field onto the customer account information so it pulls across onto orders for the customer service team. Read literally that points at four different places: the front end account, the admin account, the order, and the order email. I spent longer working out that what they actually wanted was a single field visible on the order view in the admin than I did building it. That is normal. On Magento the hard part is usually translating a vague request into the one screen that genuinely needs to change. Get that wrong and you build the right feature in the wrong place.

Adding to the admin order view

Once I knew it was the order view, the build was small. The pattern for almost any admin change is the same three moves. Find the layout handle for the page you are on, point it at a block, and render a template. For the order view that handle is sales_order_view, and you add to it from your module's adminhtml layout XML. Your block extends the backend template block, your phtml sits in your module, and the block does the work of fetching what the template needs.

The honest part of that video was the method, not the answer. I find the right layout file by searching core for the handle, then I extend an existing admin block so I inherit the things Magento already gives me rather than starting from nothing. In the block I grabbed the current order from the registry, pulled the customer by email, and handed the value to the template. In a stricter codebase you would inject the order through the request and a repository instead of leaning on the registry, and that is the better habit, but the registry approach is what you will still see in a lot of live stores.

Editing the admin grid

The companion job is getting a custom value to show in one of the admin grids, the customer grid for example. This is where people hit the wall, because the grids are not blocks you can quietly extend. They are UI listing components defined in XML, and you add a column by declaring it in your own UI component file that targets the same listing. If the attribute you want is a custom EAV attribute on the customer, you make sure it is added to the grid index so the listing has something to read. Once you have done one column you have done them all, but the first one is genuinely fiddly and there is no shame in copying a core listing and editing down from it.

Two things bite beginners here. Module load order matters, so if you are overriding or extending something another module also touches, set the sequence in your module.xml so yours loads after it. And a module has to be enabled and registered before any of this runs, which sounds obvious until you spend an hour debugging a grid column that never appears because setup:upgrade was never run.

Advanced front end modules

The other 2022 video built a front end module that added category link functionality into the layered navigation in the Luma theme. That is a good example of advanced because it is not a fresh page, it is changing behaviour that already exists and is rendered by core. The work is detective work. You find the block and template core uses for layered navigation, work out the class doing the rendering, and extend that rather than fighting it. A module is the right home for this, not the theme, because it is functionality the store relies on rather than a coat of paint, which is the same module-or-theme line I drew in the beginners piece.

My method for this never changes. Turn on developer mode, enable template hints so you can see exactly which phtml renders each part of the page, and read the layout that core ships. Once you can name the block and the template, you know what to extend and where your module plugs in. The layered navigation example also pulled a custom product collection, filtered it, and reused the existing toolbar and pagination, which is the same collection work you meet everywhere in Magento once you start building real features.

The thread through all of it

Admin modules, grid columns and advanced front end work look like three different skills, but they are one skill wearing three coats. Find the thing core already does that is closest to what you want, read how it is wired, and extend it instead of rebuilding it. The errors are your map. In developer mode Magento tells you almost exactly which class or method it expected, and the job is to read that, form a guess, and test it.

I will be straight about the wider picture, because I always am. The amount of XML, indexing and ceremony involved in a small admin change is a fair chunk of why I moved a lot of my work to headless builds, which I wrote about in why I moved from Magento to headless. Learn this anyway. Most live Magento stores are extended exactly like this, the discipline makes you a sharper developer wherever you end up, and you cannot make a sensible call about leaving a platform until you actually know how it works.