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

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).