when to use local.xml in a module

Question

I am trying to insert a new block above "Grand Total" on the checkout page, but I am really struggling so after a bit of looking I found this to help but i am still not having any success.

I first tried creating (what I thought was) the correct xml in a mymodule.xml file, when that did not work I tried adding that code to local.xml, that hasn't worked either. I know all xml files are loaded then local.xml is loaded again last in order to override previously made definitions but that leaves me wondering, can you only added new blocks to the core using local.xml or can I do it with mymodule.xml. If I can add blocks using mymodule.xml file, do I only use local.xml only when I want to move/remove/override core blocks?

I am trying to add a custom block before checkout.cart.totals (location: checkout.xml). I have tried

<reference name="checkout.cart">
    <action method="insert"><blockName>mdeprojects.remainder</blockName></action>
</reference>

<reference name="checkout.cart">
    <checkout_cart_index>
        <action method="insert"><blockName>mdeprojects.remainder</blockName></action>
    </checkout_cart_index>
</reference>

<checkout_cart_index>
    <action method="insert"><blockName>mdeprojects.remainder</blockName></action>
</checkout_cart_index>

what am I doing wrong?

===EDIT===

Now I'm getting more confused to confirm I was targeting the block I added

<checkout_cart_index>
   <remove name="checkout.cart.totals" />
</checkout_cart_index>

this worked

I then tried (for test purposes) to add the block directly to checkout.xml and my template file was not rendered.

Answer 1

Just to be clear, Magento has/is aware of two local.xml files: one at app/etc/local.xml and one under the theming structure. The former is for configuration and the latter is only for changes local to the instance. In other words, a distributed module should never use local.xml for its changes. If however you are just working on an instance you maintain, it would be fine to use local.xml, though I prefer to encapsulate changes related to a module in its own layout update file. It's not a good practice to change core layout update files, and it's not necessary most of the time.

Also, remember that there is a layout XML cache which should be cleared/disabled when making layout changes in development.

Regarding "which layout file to use", the answer is that "it doesn't matter - most of the time". When layout update XML is being used for rendering, all module files for the area (generally frontend or adminhtml) are parsed. You can generate a list of these files for frontend using the following code:

Mage::getConfig()->getXpath('frontend//file');
var_dump($cfg);

So, if all files are used for every update-based view scope, how do the different view scopes end up looking different? The answer is layout update handles, which are simply the top-level nodes in the update files. Only the contents from certain layout update handles are merged for any given scope. Beyond that, it's just a matter of setting the appropriate parent-child relationships (e.g. via insert) and using getChildHtml() in the parent template to echo your block.

So, in order for your directives to have an effect, the following conditions must be met:

• Your module's layout update file must be properly configured & have valid syntax
• Any directives you would like processed for a given view scope (including your mdeprojects.remainder <block /> directive) must be in a layout update handle which is being loaded for the desired view scope
• If you are adding your block to a parent which uses a template, you almost always will need to customize the template to render your block