Understanding Magento layout xml file (reference, block, ...)

Question

I have a some questions about the layout xml file which is placed in app\design\adminhtml\default\default\layout.

On some tutorial, it had this structure:

<layout>
    <adminhtml_example_index>
        <reference name="content">
            <block type="awesome/adminhtml_example" name="example" />
         </reference>
    </adminhtml_example_index>

    <adminhtml_example_edit>
        <reference name="content">
            <block type="awesome/adminhtml_example_edit" name="example_edit" />
        </reference>
    </adminhtml_example_edit>
</layout>

Can someone please explain what those lines mean? The tutorial can be found here: here

Thanks!

Solution 1

The XML based structure of Magento seems bit confusing and annoying at the beginning but its well-known that eventually strong capability and customizability…

<adminhtml_example_index></adminhtml_example_index>

This tag refers to the [router][controller][action] The router is the uniquely identified name for a particular dispatch. From the example you’ve given, under the admin tag of the config.xml file, we can find the router name adminhtml.

<admin>
    <routers>
        <adminhtml>
            <args>
                <modules>
                    <awesome before="Mage_Adminhtml">Super_Awesome_Adminhtml</awesome>
                </modules>
            </args>
        </adminhtml>
    </routers>
</admin>

Under that router are the module settings related to this router.

So if the url contains /admin/example/[index], magento will find the correct router which is <adminhtml> then will find the controller named example and find the correct action which is in this case index (/admin/example/ will be dispatched to the default index action)

<adminhtml_example_index>
    <reference name="content">
        <block type="awesome/adminhtml_example" name="example" />
    </reference>
</adminhtml_example_index>

In the layout file, for router controller action combinations, layout updates are defined. In here the update will be applied to the main block named as content which holds the page content section.

<block> tag is used to define the block we need to refer. <type> tag is important. It refers to the correct block class that should be used when rendering this layout (Remember in Magento’s MVC structure the View consists of both Block classes and phtml files)

In awesome/adminhtml_example here, awesome is the block configuration name mentioned in config.xml file. adminhtml_example is the block class to be used.

See

<global>
    -----
    <blocks>
        <awesome>
            <class>Super_Awesome_Block</class>
        </awesome>
    </blocks>
</global>

Under the block tag, a unique block name is defined (good naming convention will preserve the uniqueness). Then the class path for these block can be identified as Super/Awsome/Block/.

Block configuration name is now resolved. adminhtml_example is the exact block class to be used. Any underscore after block name (awesome) will be converted to directory separator.

According to that, the full path of the block class will be

[codepool]/Super/Awsome/Block/Adminhtml/Example.php

The class name will be like

class Super_Awesome_Block_Adminhtml_Example extends ….

If we have the layout file we can specify it here.. then that .phtml file will be rendered using the above block class

<reference name="root">
    <block type="page/html" name="root" template="simplepage.phtml" />
</reference>

Hope this helps.. Sorry if anything is unclear…

Solution 2

layout handlers are mapped to MVC controller so expect your handler

<adminhtml_example_index> to be used in adminhtml/example/index controller page

and

<reference name="content"> means that the blocks or other references inside those blocks will be available in content block on your theme templates

for further reading i suggest :

• http://www.magentocommerce.com/knowledge-base
• http://store.pulsestorm.net/products/no-frills-magento-layout