Saving extra data with an order in Magento

After a lot of trial and error – a lot of error – I think I have it now.

To begin with the sales_flat_order_grid is updated in Mage_Sales_Model_Mysql4_Order_Abstract::updateGridRecords(), by following the trail I worked out it inspects both the “main” table (sales_flat_order) and the main table + “_grid” (sales_flat_order_grid), takes the intersect of their columns and constructs a query from that. So any column you need in the grid table must also be in the main table. It’s not an EAV-style entity so attributes don’t need to be created.
Here is my setup script:

<?php

/* @var $this Nexxt_Booth_Model_Entity_Setup */
$installer = $this;

$installer->getConnection()->addColumn($installer->getTable('sales_flat_order'), 'box_num', 'varchar(255)');
$installer->getConnection()->addColumn($installer->getTable('sales_flat_order_grid'), 'box_num', 'varchar(255)');

Next, I needed the extra column to show in all order tables in admin. To do this I overrode each relevant block.

<?xml version="1.0"?>
<config>
    ....

    <global>
        <blocks>
            <adminhtml>
                <rewrite>
                    <customer_edit_tab_view_orders>
                    <!-- Recent 5 orders on customer page -->
                        My_Module_Block_Adminhtml_Customer_Edit_Tab_View_Orders
                    </customer_edit_tab_view_orders>
                    <customer_edit_tab_orders>
                    <!-- All orders on customer tab -->
                        My_Module_Block_Adminhtml_Customer_Edit_Tab_Orders
                    </customer_edit_tab_orders>
                    <sales_order_grid>
                    <!-- All orders in Sales menu -->
                        My_Module_Block_Adminhtml_Sales_Order_Grid
                    </sales_order_grid>
                </rewrite>
            </adminhtml>
        </blocks>
    </global>
</config>

In My/Module/Block/Adminhtml/Sales/Order/Grid.php I made the following:

<?php

class My_Module_Block_Adminhtml_Sales_Order_Grid extends Mage_Adminhtml_Block_Sales_Order_Grid

    protected function _prepareColumns()
    {
        $this->addColumn('box_num', array(
            'header'    => $this->__('Box #'),
            'index'     => 'box_num',
            'width'     => '100px'
        ));
        $this->addColumnsOrder('box_num', 'shipping_name');
        return parent::_prepareColumns();
    }

}

Similarly, in My/Module/Block/Adminhtml/Customer/Edit/Tab/Orders.php and My/Module/Block/Adminhtml/Customer/Edit/Tab/View/Orders.php I added this function:

    protected function _prepareColumns()
    {
        $this->addColumn('box_num', array(
            'header'    => $this->__('Box #'),
            'index'     => 'box_num',
            'width'     => '100px'
        ));
        $this->addColumnsOrder('box_num', (Mage::app()->isSingleStoreMode() ? 'grand_total' : 'store_id'));
        return parent::_prepareColumns();
    }

Finally, to finish off, in the event sales_convert_quote_to_order I populated the new field. This bit isn’t as important, so long as you add the data at a point before the order is saved.

$order->setBoxNum('DATA GOES HERE');