What is the proper way to add a custom dashboard “box” in the Magento backend without editing default templates?

Question

I am working on creating what I hope one day will be a publicly available Magento extension (this part I mention because it's important to me that I do the "right thing" here). One of the things I would like to do is add a box in the default Magento dashboard, basically a new "box" exactly like "Top 5 Search Terms" except with my own content. I would like my new custom box to be the last box that is displayed (ideally).

The issue that I'm running into is that the template that is responsible for rendering the dashboard calls out specific blocks to be rendered, and these blocks are nested inside of html. In other words, where often there is an area where child blocks will be rendered into a nice reasonable HTML element, in this situation it appears that specific blocks are rendered. Here is the contents of /app/design/adminhtml/default/default/template/dashboard/index.phtml

  <div class="dashboard-container">
            <?php echo $this->getChildHtml('store_switcher') ?>
            <table cellspacing="25" width="100%">
                <tr>
                    <td><?php echo $this->getChildHtml('sales') ?>
                        <div class="entry-edit">
                            <div class="entry-edit-head"><h4><?php echo $this->__('Last 5 Orders') ?></h4></div>
                            <fieldset class="np"><?php echo $this->getChildHtml('lastOrders'); ?></fieldset>
                        </div>
                        <div class="entry-edit">
                            <div class="entry-edit-head"><h4><?php echo $this->__('Last 5 Search Terms') ?></h4></div>
                            <fieldset class="np"><?php echo $this->getChildHtml('lastSearches'); ?></fieldset>
                        </div>
                        <div class="entry-edit">
                            <div class="entry-edit-head"><h4><?php echo $this->__('Top 5 Search Terms') ?></h4></div>
                            <fieldset class="np"><?php echo $this->getChildHtml('topSearches'); ?></fieldset>
                        </div>
                    </td>
                    <td>
                        <div class="entry-edit" style="border:1px solid #ccc;">
                            <?php echo $this->getChildHtml('diagrams') ?>
                            <?php if (is_array($this->getChild('diagrams')->getTabsIds())) : ?>
                                <div id="diagram_tab_content"></div>
                            <?php endif; ?>
                            <div style="margin:20px;">
                                <?php echo $this->getChildHtml('totals') ?>
                            </div>
                            <div style="margin:20px;">
                                <?php echo $this->getChildHtml('grids') ?>
                                <div id="grid_tab_content"></div>
                            </div>
                        </div>
                    </td>
                </tr>
            </table>
        </div>

If I was doing this in my own store, I believe I could achieve this relatively easily by editing the base Magento dashboard template index.phtml above, add what I need to have my block render, something like:

<div class="entry-edit">
     <div class="entry-edit-head">
         <h4><?php echo $this->__('Top 5 Search Terms') ?></h4></div>
         <fieldset class="np"><?php echo $this->getChildHtml('myDashboardBox'); ?></fieldset>
     </div>
</div>

But, this isn't my own store, so this doesn't really seem like an option.

Now, after some thought my options seem to be as follows (note that most of these seem "bad" and not something I'd be super proud to have seen in the public):

0) Something obvious that I'm not seeing that you will tell me is the perfect/right solution

1) I might (maybe?) be able to add my custom block inside of one of these other blocks in this area ("topSearches", "sales", etc) and have my block rendered. This does not seem very "clean"

2) I might be able to have the block rendered somewhere else on the dashboard page, and then move it with javascript to the correct place. This would be fairly easy I'm guessing, but feels very "hacky" for obvious reasons.

Does anybody have any feedback on the way to do this, or IF there is a way? Keep in mind that again I would like to release this module publicly so my goal is to do a good job and do as little "hacking" as possible.

Thank you very much for reading!

Answer 1

There is no really clean option, as you said, the template is coded in a non-extendable way, so there will always be some degree of hackiness. This is my personal preferred way of doing it by using event observers. This way it at least doesn't conflict with other modules.

First, add an observer for the core_block_abstract_prepare_layout_after and core_block_abstract_to_html_after event.

<adminhtml>
    <events>
        <core_block_abstract_prepare_layout_after>
            <observers>
                <your_module>
                    <class>your_module/observer</class>
                    <method>coreBlockAbstractPrepareLayoutAfter</method>
                </your_module>
            </observers>
        </core_block_abstract_prepare_layout_after>
        <core_block_abstract_to_html_after>
            <observers>
                <your_module>
                    <class>your_module/observer</class>
                    <method>coreBlockAbstractToHtmlAfter</method>
                </your_module>
            </observers>
        </core_block_abstract_to_html_after>
    </events>
</adminhtml>

These two events are dispatched for every block that is instantiated and rendered in Mage_Core_Block_Abstract. In my experience it's not such an issue using them in the adminhtml interface, but on the frontend observers for these events add too much overhead.

Back to the task at hand, you need to create the observer class.

class Your_Module_Model_Observer
{
    public function coreBlockAbstractPrepareLayoutAfter(Varien_Event_Observer $observer)
    {
        if (Mage::app()->getFrontController()->getAction()->getFullActionName() === 'adminhtml_dashboard_index')
        {
            $block = $observer->getBlock();
            if ($block->getNameInLayout() === 'dashboard')
            {
                $block->getChild('topSearches')->setUseAsDashboardHook(true);
            }
        }
    }

    public function coreBlockAbstractToHtmlAfter(Varien_Event_Observer $observer)
    {
        if (Mage::app()->getFrontController()->getAction()->getFullActionName() === 'adminhtml_dashboard_index')
        {
            if ($observer->getBlock()->getUseAsDashboardHook())
            {
                $html = $observer->getTransport()->getHtml();
                $myBlock = $observer->getBlock()->getLayout()
                    ->createBlock('you_module/block')
                    ->setTheValuesAndTemplateYouNeed('HA!');
                $html .= $myBlock->toHtml();
                $observer->getTransport()->setHtml($html);
            }
        }
    }
}

Your template will need to accomodate for the fact that you are inserting a sibling <div> from inside the sibling, but otherwise you should be fine.

</fieldset></div>
<div class="entry-edit">
    <div class="entry-edit-head"><h4>Your Module</h4></div>
    <fieldset class="np">Your Content

Leave it at that, because the parent template will be closing the <fieldset> and the <div> for you (ugly as heck, I know).