Set template in layout handle for Adminhtml

Question

In the backend of my Magento Webshop I want to set a template for the blocks of System->Config. Therefore I use the layout handle of the Mage_Adminhtml_System_ConfigController which is adminhtml_system_config_index I think. The problem is, nothing happens. Even if want to remove blocks, nothing happens:

<adminhtml_system_config_index>
    <reference name="left">
        <action method="setTemplate">
            <template>myModule/template.phtml</template>
        </action>   
    </reference>
</adminhtml_system_config_index>

OR removing block:

<adminhtml_system_config_index>
    <remove name="left" />
</adminhtml_system_config_index>

What am I doing wrong? I even tried system_config_index as layout handle.

Answer 1

You're doing three possible things wrong here.

First Tip: Are you editing the right XML file?

A lot of common layout problems come from the XML file you're editing not being the XML file that's loaded by the system. Switch on developer mode in your site, set display_errors to 1, and then deliberately introduce a non well formed error into your XML files and try to load the page.

<!-- note the trailing greater than sign at the end -->
<adminhtml_system_config_index>
    ...
</adminhtml_system_config_index> >

If the page loads without error, then you're not loading the XML file you think you are.

Second Tip: Are you using the correct layout handle?

I'm not sure you are. Despite the fact the default system configuration page uses the index action, this action actually forwards the page to the edit action.

#File: app/code/core/Mage/Adminhtml/controllers/System/ConfigController.php
public function indexAction()
{
    $this->_forward('edit');
}

Forwarding means there's an internal redispatch, but no http redirect. That means your actual handle is

`adminhtml_system_config_edit`

This is why I use (disclaimer: and built, and sell) Commerce Bug. The Layout tab always displays the current handles, and I can avoid making assumptions that send me down the wrong path.

Third Tip: Are you confusing the block named left with the left hand column?

In general, Magento's container blocks (left, content, right, etc.) are not template blocks. Instead they're container blocks (text/list blocks to be precise) that hold and multiple template blocks.

This is another place I use Commerce Bug, specifically the new Graphviz feature. This will show you the block structure for any particular page. In a factory default system, you'd see something like this for the System Configuration page

As you can see, the left block has no template, so changing its template will have no effect. The block you probably want is left.child1.

Fourth Tip: Is the block you're trying to modify added by the layout XML.

Without getting too deeply into layout rendering (which would take a book), there are some block which are added after the layout generates all its blocks. If this is the case, your block will not be available in layout XML files.

If you look at the editAction method, you can see that the tabs block is added after loadLayout is called (look for adminhtml/system_config_tabs). This means it won't be available in layout xml files.

public function editAction()
{
    //...    

    //the `loadLayout` method call creates blocks based on layout XML files
    $this->loadLayout();

    $this->_setActiveMenu('system/config');
    $this->getLayout()->getBlock('menu')->setAdditionalCacheKeyInfo(array($current));

    $this->_addBreadcrumb(Mage::helper('adminhtml')->__('System'), Mage::helper('adminhtml')->__('System'),
        $this->getUrl('*/system'));

    //this line add the `child1` block to the layout. (child one is the 
    //name chosen since the block has no explicit name
    $this->getLayout()->getBlock('left')
        ->append($this->getLayout()->createBlock('adminhtml/system_config_tabs')->initTabs());

    //...

This means you can't modify the template of this block from a layout XML file. You'll need to use a custom module that listens for an appropriate event and then makes your changes via PHP. I'd try the event controller_action_layout_render_before or controller_action_layout_render_before_adminhtml_system_config_edit with PHP code that looks something like

$block = Mage::getSingleton('core/layout')->getBlock('child1');
if($block)
{
    $block->setTemplate('foo.phtml');
}