Despatch Date Module – part 8: Customise the order grid

In this post, we’re going to add our new despatch date field as a column to the order grid page. This is the page with the list of customer orders. We’ll also add the company name as this column has also been requested by our client.

Here’s a view of what the order grid will look like when the two new columns have been added: ‘Company’ and ‘Despatch Date’.

We’re going to make some changes to our module to achieve this. We’ll add the directories shown in orange. And shown in red are the the files that we’ll add, Grid.php and Format.php, and config.xml, which we need to change.

If you’ve been following in this series, you’ll know how we can display template and block names (or ‘hints’) on our Admin pages to show us what templates and blocks we are dealing with. (See part 2.) All the work in creating the order grid page is done in the block class ‘Mage_Adminhtml_Block_Sales_Order_Grid’ which is defined in /app/code/core/Mage/Adminhtml/Sales/Order/Grid.php. We won’t need to touch the template associated with this block, app/design/adminhtml/default/default/template/widget/grid.html, because it draws on the block class for it’s content with statements like ‘ <?php foreach ($this->getColumns() as $_column): ?>’.   The ‘getColumns()’ method can be found in ‘Mage_Adminhtml_Block_Widget_Grid’, which is the parent class of ‘Mage_Adminhtml_Block_Sales_Order_Grid’.

In case you were wondering, the template is tied to the class ‘Mage_Adminhtml_Block_Sales_Order_Grid’ in the class’s parent class ‘Mage_Adminhtml_Block_Widget_Grid’in the constructor method thus: ‘$this->setTemplate(‘widget/grid.phtml’);’. For the uninitiated, setting the template in the block class (‘programmatically’) is an alternative to setting it in the layout xml file.

We’ll extend ‘Mage_Adminhtml_Block_Sales_Order_Grid’ within our module in a new class ‘Blessthemoon_Despatchdate_Block_Adminhtml_Sales_Order_Grid’ defined in a new file Blessthemoon/despatchdate/Block/Adminhtml/Sales/Order/Grid.php. For the sake of good organisation, we’ve set up the directory path within our module to mirror the directory path of Mage/Adminhtml/Block/Sales/Order/Grid.php. We are overriding the methods ‘_prepareCollection()’ and ‘_prepareColumns()’. The first of these methods ‘_prepareCollection()’ is shown in the following code with additions in red.

The ‘_prepareCollection()’ method in line 7 starts by instantiating the model collection. The ‘getCollectionClass’ method, which can be found in our new class’s parent, will get the resource model ‘sales/order_grid_collection’. This model accesses values directly from the ‘sales_flat_order_grid’ table in the database. All columns in the out-of-the-box default order grid are taken directly from this table. However, the column ‘est_date’ (despatch date) resides in the ‘sales_flat_order’ table, and the column ‘company’ resides in the ‘sales_flat_order_address’ table.

To access columns in other tables we need to use SQL joins as you can see in lines 8 and 10 of the code. The joins we need are shown in the diagram.

In line 8 of the code, you can see, how we access ‘company’. We join, where the ‘parent_id’ column in the ‘sales_flat_order_address’ table is equal to the ‘entity_id’ column in the ‘sales_flat_order_grid’ table (‘main_table’). As there are multiple addresses for each order, we select where ‘address_type=\’billing\”. To ensure we select only one record for each order, we use ‘getSelect()->distinct()’ in line 9. Similarly, in line 10 we access the column ‘estdate’ by joining where the ‘entity_id’ column in the ‘sales_flat_order’ table is equal to the ‘entity_id’ column in the ‘sales_flat_order_grid’ table (‘main_table’).

Now that we have our collection, we can add the extra columns to the grid that we need. The following code shows the rest of our Grid.php file with the changes we’ll make to the ‘_prepareColumns()’ method shown in red.

The ‘addColumn’ method takes two arguments, an id and an array containing key value pairs to describe the column required. For ‘company’, the array specifies the ‘header’ which is ‘Company’ and the table column required with ‘index’ which is ‘company’. For ‘estdate’ (the despatch date’), in addition to ‘header’ and ‘index’, we identify with ‘align’ that we want the column ‘right’ aligned. We also use ‘renderer’ which allows us to specify how we want the values transformed or formatted to appear in the order grid. To do this we specify a class name, and we’ll need to build this class with the method ‘render’, which will be called when this block class is instantiated.

This code shows our new class which is located in ‘Renderer/Format.php’ along side our block file Grid.php. (See the module structure diagram above for a reminder.)

The new class extends ‘Mage_Adminhtml_Block_Widget_Grid_Column_Renderer_Action’ (line 3) which has the method ‘render’ which we want to override. For the currently rendered row passed into the method as $row, the method uses ‘getData’. Whereas, ‘getData()’ without any parameters gets an array of all attributes and their values for the current order id, in this case, with ‘$this->getColumn()->getIndex()’, we obtain the value of just the column specified by ‘index’ within ‘addColumn(‘estdate’,array(…,’index’=>’estdate’,…)’, i.e. ‘estdate’.

Next in lines 9 through 11, we transform the date from ‘YYY/MM/DD’ to ‘DD/MM/YYYY’ and return it. We could use ‘render’ to do much more as needed. For example, returning color coded dates based on whether the the despatch date is before or after today’s date.

With our block class, Grid.php, and its supporting class, Format.php, completed, we’ve just some housekeeping to take care of before we’re ready for testing. We need to tell Magento in config.xml about these two new block classes. These lines are shown in red.

If you worked through part 7 of this series, you may recall how we used the ‘rewrite’ tag to override a model class. Here we’ve used the same syntax to override our block classes in ‘<sales_order_grid>’ and ‘<widget_grid_column_renderer_action>’ within ‘<adminhtml>’.

We’re there! We should have both ‘Despatch Date’ and ‘Company’ displayed nicely in our order grid page. In the next post, we’ll look at how we can also display the despatch date for customers in their ‘My Account’ area for any orders they’ve made.