Module Development Series – Magento Admin Module – Part1

Banners
In this blog post, we will see how to set up admin pages for your module. Specifically in this blog post i will show the basic of how to set up Grid in magento.

Before reading this blog, I assume you are familiar with basics of magento module development and have used Models,Collections. Now, lets start: The name of module I am using is Excellence_Employee, so all classes will be named accordingly. Please change class name as per your module.
Note: You can easily generate admin pages of your module using Module Creator. But to understand in detail how everything works, please go through this blog.

Admin Grid

First create an ‘Adminhtml’ folder inside the Block folder of your module. And then create an Employee.php file. Here is a screen shot of entire file structure of our module Magento Admin Module File Structure
So, the Employee.php file is our grid container file, the code for this file is as follows

<?php
class Excellence_Employee_Block_Adminhtml_Employee extends Mage_Adminhtml_Block_Widget_Grid_Container
{
  public function __construct()
  {
    $this->_controller = 'adminhtml_employee';
    $this->_blockGroup = 'employee';
    $this->_headerText = Mage::helper('employee')->__('Employee Manager');
    $this->_addButtonLabel = Mage::helper('employee')->__('Add Employee');
    parent::__construct();
  }
}

Now, lets now go line by line of this file.

class Excellence_Employee_Block_Adminhtml_Employee extends Mage_Adminhtml_Block_Widget_Grid_Container

Here our class extends the Mage_Adminhtml_Block_Widget_Grid_Container class, this is very important for our Grid to work. Next we have

$this->_controller = 'adminhtml_employee';
$this->_blockGroup = 'employee';

This lines are very important, both these variables tell magento the location of our Grid.php file. If you open th eMage_Adminhtml_Block_Widget_Grid_Container class, there inside _prepareLayout() function, you will see

protected function _prepareLayout()
    {
        $this->setChild( 'grid',
            $this->getLayout()->createBlock( $this->_blockGroup.'/' . $this->_controller . '_grid',
            $this->_controller . '.grid')->setSaveParametersInSession(true) );
        return parent::_prepareLayout();
    }

So, we can see here the location of our Grid file, is located by magento based on these two variables. So in short the class name of our Grid file should be,

$this->_blockGroup.'/' . $this->_controller . '_grid'
//or 
employee/adminhtml_employee_grid

This concept, is important when you want to have multiple grids in your module
Next, we will create our Grid.php file. As mentioned above we will create our php at
Excellence/Employee/Block/Adminhtml/Employee/Grid.php

<?php

class Excellence_Employee_Block_Adminhtml_Employee_Grid extends Mage_Adminhtml_Block_Widget_Grid
{
	public function __construct()
	{
		parent::__construct();
		$this->setId('employeeGrid');
		$this->setDefaultSort('id');
		$this->setDefaultDir('ASC');
		$this->setSaveParametersInSession(true);
	}

	protected function _prepareCollection()
	{
		$collection = Mage::getModel('employee/employee')->getCollection();
		$this->setCollection($collection);
		return parent::_prepareCollection();
	}

	protected function _prepareColumns()
	{
		$this->addColumn('id', array(
          'header'    => Mage::helper('employee')->__('ID'),
          'align'     =>'right',
          'width'     => '10px',
          'index'     => 'id',
		));

		$this->addColumn('name', array(
          'header'    => Mage::helper('employee')->__('Name'),
          'align'     =>'left',
          'index'     => 'name',
		  'width'     => '50px',
		));

		 
		$this->addColumn('content', array(
			'header'    => Mage::helper('employee')->__('Description'),
			'width'     => '150px',
			'index'     => 'content',
		));
		return parent::_prepareColumns();
	}
}

Now as you can see our class needs to extend Mage_Adminhtml_Block_Widget_Grid class, this is important.

  • $this->setId(’employeeGrid’) ==> This set’s the ID of our grid i.e the html id attribute of the <div>. If you’re using multiple grids in a page then id needs to be unique
  • $this->setDefaultSort(‘id’) ==> This tells which sorting column to use in our grid. Which column should be used for default sorting
  • $this->setDefaultDir(‘ASC’) ==> The default sorting order, ascending or descending
  • $this->setSaveParametersInSession(true) ==> this basically sets your grid operations in session. Example, if we were on page2 of grid or we had searched something on grid when refreshing or coming back to the page, the grid operations will still be there. It won’t revert back to its default form.

Next we have _prepareCollection() function. This function is simple, it just returns a collection of the module we want to show in our grid. For advance collection functions read this blog post.
Next we have the _prepareColumns() function. Here we add columns to our grid.

$this->addColumn('id', array(
          'header'    => Mage::helper('employee')->__('ID'),
          'align'     =>'right',
          'width'     => '10px',
          'index'     => 'id',
		));
  • ‘id’ an unique id for column
  • ‘header’ is the name of the column
  • ‘index’ is the field from our collection. This ‘id’ column needs to be present in our collection’s models.

This is all that is needed for the showing the grid. Now, let create our controller so that we can view the grid in admin.

Admin Controller and Admin Menu

To add our module menu in admin, open the config.xml file of the module and add the following directly in the >config;< tag

<adminhtml>
		<menu>
			<employee module="employee">
				<title>Employee</title>
				<sort_order>71</sort_order>               
				<children>
					<items module="employee">
						<title>Manage Employees</title>
						<sort_order>0</sort_order>
					<action>employee/adminhtml_employee</action>
					</items>
				</children>
			</employee>
		</menu>
		<acl>
			<resources>
				<all>
					<title>Allow Everything</title>
				</all>
				<admin>
					<children>
						<Excellence_Employee>
							<title>Employee Module</title>
							<sort_order>10</sort_order>
						</Excellence_Employee>
					</children>
				</admin>
			</resources>
		</acl>
		<layout>
			<updates>
				<employee>
					<file>employee.xml</file>
				</employee>
			</updates>
		</layout>
    </adminhtml>   

I will explain the >acl< tag later, but for now focus on the >menu< tag.
The >action< is the URL of our admin controller. Suppose, if we want to add 2 menu items, we need to use the following

<children>
					<items module="employee">
						<title>Manage Employees</title>
						<sort_order>0</sort_order>
					<action>employee/adminhtml_employee</action>
					</items>
                                         <items2 module="employee">
						<title>Manage Employees</title>
						<sort_order>0</sort_order>
					<action>employee/adminhtml_employee2</action>
					</items2>
				</children>

Now, let create our controller file. Create an ‘Adminhtml’ folder in the controllers folder, as shown in the folder structure above. Next we will create our EmployeeController.php file

class Excellence_Employee_Adminhtml_EmployeeController extends Mage_Adminhtml_Controller_action
{

	public function indexAction() {
		$this->loadLayout();
                $this->renderLayout();
	}

This is same as our standard controller, only we need to extend a different class. Next, create an employee.xml layout file in our adminhtml layouts i.e design/adminhtml/default/default/layout/employee.xml. And in our config.xml we will add the entry of this new layout file, so magento knows to read this layout file as well. We have already done this above in the >adminhtml< tag. Now, the content of employee.xml is

<?xml version="1.0"?>
<layout version="0.1.0">
    <employee_adminhtml_employee_index>
        <reference name="content">
            <block type="employee/adminhtml_employee" name="employee" />
        </reference>
    </employee_adminhtml_employee_index>
</layout>

We are simply adding our Grid Container blog to the content area. For more details on layout read this blog. So now when we click the menu item from admin, it should show our grid.Admin Grid