The Magento Designer’s Guide has the following short intro about layout XML and I think it explains it quite well, although I will go through some more detail with examples afterwards.

Layout is a virtual component of the Magento application. By modifying the components of layout, you can build your store page in an upgrade-compatible way.

Layout is comprised of default layout and layout updates that are made up of easy-to-learn XML tags. With these layout commands, you can modify/assign content block-structural block relationships and also control store-front functionalities such as loading and unloading of block-specific Javascripts to a page.

Layout files are separated on a per-module basis, every module bringing with it its own layout file (for instance ‘catalog.xml’ is a layout file for the catalog module, ‘customer.xml’ is for the customer module…etc). These layout files are located in app/design/frontend/your_interface/your_theme/layout/ and each file is further separated by handles, each handle (with the exception of ) assigning its nested updates to the according specific page in the store.

Some layout files may contain the handle. When parsing the layout files, Magento first grabs the layout updates assigned in the handle of almost all layout files, reading them in the order as assigned in app/etc/modules/Mage_All.xml. It then parses the page-specific layout update, finalizing the building of a store page.

The system is built this way in order to allow seamless addition and removal of modules without effecting other modules in the system.

Basically you start off with the default handle and this specified a template to use. The templates are phtml files – essentially html but with additional tags specific to Magento. The template can refer to blocks, as can the layout.xml – where the coincide the content described in the layout is injected into the html. The templates usually specify a module and a template to go with that block, allowing for standard modules (such as loading a products data) to be combined with custom templates to style the data.

This system of “imaginary” blocks is quite confusing and you often end up working with three or four files in different folders all contributing to a single area of the page. The reason this is a good thing, is for module/plugin developers since they can write simple, self-contained plugins that can add and affect lots of different bits of the Magento admin and front-end where it is appropriate to do so. Other systems just cannot do this in such a concise way, although it does give theme designers a headache.

As already mentioned, each addition to the layout file injects content (or in fact could hide/modify content) within a template. The snippet of XML you need to add to insert content will specify a block and its type in order to get it’s data and likely a template to display that data. There are hundreds of included block types that Magento uses for displaying everything from CMS Pages to Layered Price Details. One of the most useful however is core/text_list.

The core bit references the core module and the text_list refers to the class that is being used. For anyone interested, you can find this class in app/code/core/Mage/Core/Block/Text/List.php

What this block does is allow you to add other blocks to it, for an example of this check your page.xml layout file and look for the default handle. Within the default handle there will be a block named root that specifies the page template and within the root block you will likely find lots of instances of core/text_list being used – like the left column.

<block type="core/text_list" name="left" as="left" translate="label"><label>Left Column</label></block>

The various layout files (each one coincides with a module) can then add their own blocks to that left column. In this way the Checkout module adds the shopping cart to the right column and the Reports module adds the products viewed there as well.

This mechanism is extremely useful because you can also specify layout updates from within the Magento admin system. Products, categories and CMS pages can all have their own layout xml added in their respective design tabs. See the screenshot below for an example of this in action.

So, any XML that you can use inside a normal layout file can be used for a specific CMS page for example. In th example above we have a custom template which retains the normal content block for the CMS content and adds three additional blocks called homepage_leftcol, homepage_fullcol1 and homepage_fullcol2. These are mentioned in the page layout file under the default handle but if you are using existing blocks such as content, left or right then you don’t need to worry about that. You can then simply add blocks to them using the normal syntax. In this case we add content using custom modules called categorytitle and featuredproduct but they can be anything.

The most common use for this would probably be to add a CMS Static Block to one of the sidebars or similar. This would be done by adding the below XML to your layout. Remember this can be done for products and categories as well as CMS Pages – so it is an ideas way to cross-sell or add banners to pages.

<reference name="right">
   <block type="cms/block" name="whatever_you_want_to_call_it" after="name_of_another_block">
      <action method="setBlockId"><block_id>cms_block_reference</block_id></action>
   </block>
</reference>