In this article, we will be covering the basics of Magento layout XML. 

We will go over local.xml and do some basic modifications. This will include adding and removing scripts, removing blocks and adding layout changes.

Now that we have a basic understanding of the theme hierarchy from the first article in this series, we will dive a little deeper and explain the templating files.

The templating files consist of two sub-directories of which are:

• Layout: app/design/frontend/<package_name>/<theme_name>/layout/
• Template: app/design/frontend/<package_name>/<theme_name>/template/

There is a lot to cover, for this reason I will be splitting them out into their own articles. Today we will just be covering the layout aspect. The template aspect will come into play in the next article.

Wait, before we even get started we need to do one vital thing which is to disable Magento cache, if you haven't already done so, that is! In doing so, it will allow us to view our modifications instantly rather than having to refresh the cache each time we make a change. Ideally it should be turned off during development of a site. To do this log into the admin area and head over to system > cache management and disable all.

Now that's sorted let's begin.

Layout

The layout folder contains the XML files that largely dictates what is displayed on the front end of the store. The layout structure is quite complex in Magento, yet this is one of the reasons that makes it so powerful and flexible. 

You will find hundreds of XML files each doing their own thing, each view or module in app/code/ gets it's layout specified by its own XML file. If you ever install a third party module onto your store and it affects the front end it will no doubt have its own XML file.

So, how do I know which file to edit if I need to?

Well, the naming convention of the files makes it easier to track down when you need to make modifications. For example, Magento app/code/core/Mage/Page/ module has its own XML file named app/design/frontend/base/default/layout/page.xml as you can see there's a pattern starting to emerge here! Once you have familiarized yourself and done a few stores you will soon notice some repetitiveness and recall which files you need to edit.

Note: Please be aware of third party modules, as technically the developer can name their XML file anything they desire. In this scenario, unless it's in their documentation, you will have to hunt down the name of the file within the module itself usually found in the config.xml file. Also note not all modules have an XML file, usually the XML file will only be present if it affects the front end of the store so don't expect one all the time!

Path to config: app/code/local/<name_space>/<module>/etc/config.xml

Notice I have referenced base/default above, remember these are where the core files reside, if you need to make modifications always copy it over to your own package/theme never edit base/default files. 

Like so:

app/design/frontend/base/default/layout/page.xml

copy to:

app/design/frontend/<package_name>/<theme_name>/layout/page.xml

Heavily modifying these files does require experience and with this being a beginners tutorial, it's beyond the scope of this series; however, I will run through local.xml and how this ties in with theme development as well as covering a handful of basic modifications which I think will be useful.

What is local.xml?

Put simply, it's a file that's placed within our theme layout folder that will house a large portion of our overrides or updates to XML references for that theme. It's considered good practice and Magento recommends it. We could look at it as Magento version of WordPress functions.php file.

Wait, a "large portion" why not "all" of our overrides or updates?

There is a debate on this topic and if we did a bit of research we will find everyone has their own opinion. Some will say only use local.xml and don't make edits anywhere else while others will disagree, so don't take the following set in stone.

Personally I think it's a great place for small modifications, such as adding blocks, removing blocks or changing templates. It isn't a place to completely layout your product page or the like, if you want to do that, do it in the relevant file e.g catalog.xml

Yeah, it might save us a bit of time when we upgrade Magento as all our edits are in one single file but getting all our edits in one single file in the first place, with all the headaches of trying to override other XML files, it simply gets outweighed.

Furthermore when were doing a large amount of modifications to a page we ideally want to reference the other XML that's part of that page, we would have to constantly switch between the two files, and in the end were splitting up functionality between two separate files - not what we really want!

So, how to set it up...

Create the local.xml file inside our theme layout folder app/design/frontend/<package_name>/default/layout/local.xml and add some basic XML markup structure:

<?xml version="1.0"?>
<!--
/*
 * Store Name
 * Store URL
 *
 * @description  Layout modifications
 * @author       Author Name
 * @package      packagename_default
 *
 */
-->
<layout version="0.1.0">
    <!-- our modifications will go here -->
</layout>

Now that we have our file ready I will show you a handful of common techniques.

1. Adding and Removing Scripts / Stylesheets

A very common modification is to add or remove JavaScript and CSS. If your working with jQuery you will have to add this in as Magento does not include it by default and any custom JavaScript you require will also need adding in.

If we view source on a Magento installation we will see a whole bunch of JavaScript being pulled in, some of which we won't use, in which case it needs removing as its an unnecessary http request - Magento isn't quick so let's do the basics right!

To include a file, we need to decide if it's going to be global e.g on every page of our store or just certain areas. With this we can select the correct layout handle to use.

I will introduce two layout handles, <default> and <cms_index_index>. Of course, there are many more available to us, but for now lets focus on just these.

The <default> handle is global and will affect all pages while the <cms_index_index> will only affect the home page.

Now, on to the code.

<?xml version="1.0"?>
<layout version="0.1.0">
    <default>
        <reference name="head">
            <!-- jQuery locally -->
            <action method="addItem"><type>skin_js</type><name>js/libs/jquery.min.js</name></action>

            <!-- jQuery CDN -->
            <block type="core/text" name="cdn.jquery">
                <action method="setText">
                    <text>
                        <![CDATA[
                        <script type="text/javascript" src="http://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
                        <script type="text/javascript">jQuery.noConflict();</script>
                        ]]>
                    </text>
                </action>
            </block>

            <!-- add some items (globally) -->
            <action method="addItem"><type>skin_js</type><name>js/libs/modernizr.min.js</name></action>
            <action method="addItem"><type>skin_js</type><name>js/libs/html5shiv.min.js</name><params/><if>lt IE 9</if></action>
            <action method="addItem"><type>skin_js</type><name>js/libs/respond.min.js</name><params/><if>lt IE 9</if></action>
            <action method="addItem"><type>skin_js</type><name>js/libs/selectivizr.min.js</name><params/><if>lt IE 9</if></action>

            <!-- remove some items (globally) -->
            <action method="removeItem"><type>skin_css</type><name>css/widgets.css</name></action>
            <action method="removeItem"><type>skin_css</type><name>css/print.css</name></action>
            <action method="removeItem"><type>skin_css</type><name>css/styles-ie.css</name><params/><if>lt IE 8</if></action>
            <action method="removeItem"><type>skin_js</type><name>js/ie6.js</name><if>lt IE 7</if></action>
            <action method="removeItem"><type>js</type><name>lib/ds-sleight.js</name><params/><if>lt IE 7</if></action>
        </reference>
    </default>

    <cms_index_index>
        <reference name="head">
            <!-- add items just on the homepage -->
            <action method="addItem"><type>skin_js</type><name>js/libs/home.min.js</name></action>
            <action method="addItem"><type>skin_css</type><name>css/home.css</name></action>
        </reference>
    </cms_index_index>
</layout>

There's quite a lot going on here but when broken down it's relatively straight forward.

<action method="{addItem or removeItem}">
    <type>{type of file / location}</type>
    <name>{path to the file}</name>
</action>

1. Method is where we enter what we want to achieve
2. Type references the type of file it is and also dictates where the file is in the hierarchy.
3. Name is where we enter the path to the file

Following up on point two: It also dictates where the file is in the hierarchy, each type references a different position in the hierarchy which gets prepended to what you enter in the <name> field. I've listed them below for reference:

• skin_js: skin/frontend/<package_name>/default/{name}
  
• skin_css: skin/frontend/<package_name>/default/{name}

• js: js/{name}
  

Notice that loading a file from an external source such as a CDN has a slightly different syntax. Also it's important to include the jQuery.noConflict(); at the end to avoid jQuery conflicting with Magento built in Prototype library.

2. Removing Blocks

Magento comes bundled with multiple sidebar blocks that let's face it we are never going use in a real life situation, such as the "Back to School" advert. Below are two methods we can use: 

<?xml version="1.0"?>
<layout version="0.1.0">
    <default>
        <!-- remove a block -->
        <remove name="right.permanent.callout" />
    
        <!-- unset a block -->
        <reference name="right">
            <action method="unsetChild"><name>right.poll</name></action>
        </reference>
    </default>
</layout>

The remove method is a good way to remove a block regardless of which layout handle loaded the block, sometimes we just want it gone globally no matter where it is and to never return!

On the other hand unsetChild will only remove a block from within a specific layout handle. You can see I'm calling it within the right layout handle so it will only be removed from there. If the right.poll block is called from anywhere else in a different layout handle it will get displayed.

3. Adding a Layout Change

Here we have an example of adding in an additional structural block to the homepage. We are referencing the content block and using the after tag to specify the block to display at the end of the content block.

<?xml version="1.0"?>
<layout version="0.1.0">
    <cms_index_index>
        <reference name="content">
            <block type="core/template" name="home.additional" after="-" template="/home/additional.phtml" />
        </reference>
    </cms_index_index>
</layout>

4. Adding a Static CMS Block

Lastly we have an example of adding in a static CMS block, but first you'll need to create one for this to work.

Once logged into the admin area head over to CMS > Static Blocks and add a new block. Take note of the "Identifier" as we need to reference this in the XML code.

<?xml version="1.0"?>
<layout version="0.1.0">
    <cms_index_index>
        <reference name="content">
            <block type="cms/block" name="home.static.block" after="-">
                <action method="setBlockId"><block_id>home_static_block</block_id></action>
            </block>
        </reference>
    </cms_index_index>
</layout>

Within the block_id is where we enter our identifier.

Further Reading

We have barely scratched the surface and there are many other uses for XML not to mention more layout handles and XML tags available to us. Magento layout itself warrants to be a series as there is a great deal to cover, for now I am keeping it to just the basics.

If you want to do some more reading up on the XML I would recommend reading this article and also download a copy of Magento Official Design Guide which goes into more depth and has a good explanation of the other XML tags we can use.

What's Next?

In the next article, we're going to push forward and look into the template files.