Incorrect loading order of Layout XML

Question

When I create a layout file for the admin area (whether in the community or local code pool), sometimes Magento is loading that layout xml in before the Adminhtml module layout xml is loaded. The effect is that reference calls are discarded because there is no block created to apply them to.

Obviously, caching is not playing a part here. I have added Mage_Adminhtml in the <depends/> node in the module declaration file.

Is this an issue that you have had before? If so, how is it resolved?

I have worked through this issue a number of times, and get to a solution each time, but I can't figure what causes this to happen in the first place.

Answer 1

It's hard to say without a concrete example, but I suspect you're running into a file order vs. handle order problem.

Specifically, Magento loads its XML files in module order, with local.xml tacked on last. Here's a typical list, in order

frontend/base/default/layout/core.xml
frontend/rwd/default/layout/page.xml
frontend/rwd/default/layout/directory.xml
frontend/rwd/default/layout/cms.xml
frontend/rwd/default/layout/customer.xml
frontend/rwd/default/layout/catalog.xml
frontend/rwd/default/layout/catalog_msrp.xml
frontend/rwd/default/layout/catalogsearch.xml
frontend/base/default/layout/payment.xml
frontend/rwd/default/layout/sales.xml
frontend/base/default/layout/sales/billing_agreement.xml
frontend/base/default/layout/sales/recurring_profile.xml
frontend/base/default/layout/cataloginventory.xml
frontend/base/default/layout/shipping.xml
frontend/rwd/default/layout/checkout.xml
frontend/rwd/default/layout/paypal.xml
frontend/base/default/layout/bml.xml
frontend/rwd/default/layout/poll.xml
frontend/rwd/default/layout/review.xml
frontend/rwd/default/layout/tag.xml
frontend/base/default/layout/reports.xml
frontend/base/default/layout/googleanalytics.xml
frontend/rwd/default/layout/wishlist.xml
frontend/base/default/layout/paypaluk.xml
frontend/base/default/layout/giftmessage.xml
frontend/rwd/default/layout/contacts.xml
frontend/base/default/layout/sendfriend.xml
frontend/rwd/default/layout/rss.xml
frontend/base/default/layout/productalert.xml
frontend/rwd/default/layout/oauth.xml
frontend/base/default/layout/authorizenet.xml
frontend/rwd/default/layout/bundle.xml
frontend/rwd/default/layout/captcha.xml
frontend/base/default/layout/centinel.xml
frontend/rwd/default/layout/newsletter.xml
frontend/rwd/default/layout/downloadable.xml
frontend/base/default/layout/pagecache.xml
frontend/rwd/default/layout/persistent.xml
frontend/base/default/layout/weee.xml
frontend/base/default/layout/xmlconnect.xml
frontend/base/default/layout/moneybookers.xml
frontend/base/default/layout/pulsestorm_checkoutstep.xml
frontend/rwd/default/layout/local.xml

The order layout XML files are loaded in dictates the order layout XML rules are applied — per handle. It's this last part that trips people up. Handles are those top level XML nodes.

<config>
    <handle_name>
    </handle_name>
</config>

Handles are sort of like events for the layout — for every page request Magento issues a number of handles. You can use Commerce Bug to see which handles are issued for a particular page request

For those with images turned off, the handles issued for that particular page request were

<default />
<catalog_category_layered_nochildren />
<STORE_default />
<THEME_frontend_rwd_default />
<catalog_category_view />
<catalog_category_default />
<CATEGORY_3 />

What this means is, Magento will run every default XML chunk: first for the core.xml file, then every default chunk for the page.xml file, all the way down to local.xml.

Then, Magento will run every catalog_category_layered_nochildren XML chunk: first for the core.xml file, then for the page.xml file, all the way down to local.xml.

This continues for each handle.

What this means is, if you have a bit of layout update XML in local.xml inside a default handle, it will run before a bit of layout update XML in core.xml that's inside the catalog_category_layered_nochildren handle. This is, by far, the thing that causes the most confusion in the layout XML system, especially since there's a bit of conventional wisdom floating around that says "local.xml loads last".

If the above confused you a bit and you need to learn more about the Layout XML system, I still think my book No Frills Magento Layout is the best way to learn the system inside out.