Understanding how magento merges layout XML data

Question

How does Magento handle layout XML files?

For example if I have created a theme app/design/frontend/example/theme and copy an XML file from the base/default/layout directory in my theme's layout directory:

• Does it override the whole file? Meaning will I have to copy the XML file into my theme to begin overriding things, or
• Does it merge with the base/default and override only the changes I have made in my XML file?

Answer 1

In brief, this is how Magento loads layout files:

1. When loading a theme, Magento reads the configuration of all the available modules, and checks which layout files should be loaded.
2. For each file, Magento tries to load it from your theme.
   If it exists in your theme, it loads it and goes directly to step 4.
3. If the file doesn't exist in your theme, it tries to load it from the base/default theme.
4. Magento parses the XML files and merges them into one.
5. Magento looks for a local.xml file in your theme, and appends whatever is there, to the previously merged layout handles.

So, unless absolutely required,

• Use the local.xml for changing the layout of a theme, instead of copy/pasting the xml files from base to your theme.
• Create your own layout files for your own custom modules.

Tip
It - almost - doesn't matter if a layout handle exists in foo.xml or bar.xml.
I've seen implementation where people copy/paste catalog.xml to their own theme, because they think that's the only place where they can edit "catalog-related" handles.
The difference you would notice between adding a handle in foo.xml instead of bar.xml, is that a block would be appended in a different order, depending on which layout file was first loaded.