Sometimes Magento still confuses me when I try to create adminhtml pages and widgets like tabs or grids. One interesting example is that I needed a grid inside an edit form for a one-to-many relationship - just like how the coupons form and grid is located inside of a shopping cart pricerule.
In this article I’ll explain some of Magento’s most common adminhtml blocks and how they can be used.
Introducing the adminhtml blocks
Mage_Adminhtml_Block_Template: pretty much the same as the normal template block, except it contains a method to get the formkey and throws the
adminhtml_block_html_before event. It's extended by most blocks I'm going to describe.
Mage_Adminhtml_Block_Widget: generic widget class. Contains various methods for generating HTML for buttons and icons.
Mage_Adminhtml_Block_Widget_Container: mostly contains logic for adding buttons.
Mage_Adminhtml_Block_Widget_Form: Your class that extends it, is responsible for creating and containing your form (
_prepareForm method is where you set your form details such as enctype, method (post or get) and action.
Mage_Adminhtml_Block_Widget_Grid: Renders a grid which you can pass a collection of models to. Automatically handles filtering and searching.
Adds a header and footer to your grid, and creates the “Add” button. Also extends
When this block is in
content, the layout switches to something similar to a col2-left layout with tabs on the left side. Contains logic for adding/removing tabs.
Interface for any blocks that can be used as tabs. Has methods such as
canShowTab Any block can implement this interface. The normal
_toHtml method is used to render the tab content. Usually you will see Widget Forms or Text List blocks implementing this interface.
Layout and block order
Now you know what the main blocks are, let's look at how an avarage layout xml of an adminhtml page looks like.
Note: I've removed the names of the blocks for simplicity.
Notable is that
content contains the form container, even though all the other forms are rendered inside left.
Also cool is that the coupons grid and generate coupons form can be inside a form. This structure is handy for models that have a one to many relationship. In this case, a rule can have multiple coupons. Keep in mind though that when you have this structure, the input’s of the grid column filtering will be part of the data you submit. To avoid id conflicts, you have to give the columns a different id.
This should give you a slightly better idea on how to construct adminhtml pages. And remember to always look at the core code for the specific implementation details, as Magento lacks good documentation.