Magento – update layout using custom layout handles

layoutxml

i'm fairly new to magento, so i might not get all terms right. it's also possible that i haven't fully understood the magento internals which work through layouts and templates to print a webpage to the customer.
i followed some simple tutorial to add a module to magento which provides me three additional options too choose from when setting the page_layout for categories/products.
so far so good. the entries show up in admin backend and the templates i associated to these page_layouts are correctly loaded if i browse to a custom layout category.

i've removed and added plenty of blocks via local.xml. i've been using <default> (which targets all layouts iirc) and <catalog_category_default> (which is parsed when browsing a category). so in know how to use and "<block type="foo/myblock" name="my.precious.block" /> to remove or display a block.

now i want to add a block to one of my custom layouts.
my /magento/app/code/local/Foo/Layout/etc/config.xml looks like this:

<?xml version="1.0"?>
<config>
    <modules>
        <Foo_Layout>
            <version>0.0.1</version>
        </Foo_Layout>
    </modules>
    <global>
        <page>
            <layouts>
                <foo_category_a module="page" translate="label">
                    <label>CustomCategory (A)</label>
                    <template>page/category_a.phtml</template>
                    <layout_handle>foo_cat_a</layout_handle>
                    <update handle="foo_cat_a" />
                </foo_category_a>
            </layouts>
        </page>
    </global>
</config>

/app/etc/modules/Foo_Layout.xml looks like this:

<?xml version="1.0"?>
<config>
    <modules>
        <Foo_Layout>
            <active>true</active>
            <codePool>local</codePool>
            <depends>
                <Mage_Page />
            </depends>
        </Foo_Layout>
    </modules>
</config>

and my /app/design/frontend/default/foo/layout/local.xml like this:

<?xml version="1.0"?>
<layout version="0.1.0">  
    <default>
        <reference name="head">
            <action method="addCss"><stylesheet>css/foo.css</stylesheet></action>
        </reference>

        <reference name="header">
            <remove name="topSearch" />
        </reference>

        <reference name="right">
            <remove name="right.permanent.callout" />
        </reference>

        <reference name="left">
            <remove name="left.permanent.callout" />
        </reference>

        <reference name="root">
            <block type="core/template" name="top.search" as="topSearch" template="catalogsearch/form.mini.phtml" />
        </reference>
    </default>

    <!--
        category view mods
    -->
    <catalog_category_default>
        <reference name="left">
            <remove name="catalog.leftnav" />
            <remove name="currency" />
            <remove name="tags_popular" />
        </reference>
    </catalog_category_default>

    <foo_cat_a>
        <remove name="products.info" />
    </foo_cat_a>
</layout>

so i have:
layouts added: check
selectable in admin: check
correctly loading the specified templates: check
being able to add blocks to custom layout: fail 🙁

what am i missing here? i searched the web up and down, tried many different locations for layout-definition and the layout-update-code, but nothing worked so far.

the predefined handles work well (e.g. <catalog_category_default>) but not those defined by me.

greetings
patrick

Best Answer

<update handle="foo_cat_a" /> might not work because it is likely being parsed before the handle (which typically adds the product.info block handle) is being parsed.

To debug handle load/merge order you can follow the directions I have specified here