Custom Layouts and Templates with Magento

In the first part of this series, we learned the basics of Magento module development including the Magento directory structure, the custom module structure, and we created a basic "Hello World" module in order to understand how controllers work in Magento.

In this article, we will learn how to create blocks and layouts files. Specifically, we'll look at how layout files and blocks files work in Magento and we'll look at the rendering of layout files.

First, we will see what the layout and block files are and how they are useful in rendering front-end pages in Magento, and then we will see how we can include them in our custom module.

What Is the Layout File?

As the name suggests, layout files are useful in rendering front pages of Magento. Layout files are XML files that reside in in app > design > frontend > your interface > your theme > layout. Here, you can see that there are many layout files for any given module. Each Magento module has its own layout files much like the customer module has the customer.xml layout file, catalog module have catalog.xml layout file etc. These layout files contain structural blocks and content blocks.

If you're wondering why Magento needs these blocks, you can learn more about this in the first part of the series.

Let's Dig More Into Layout Files

Let's dig more into layout files by looking at one example. Go to app > design > frontend > base > layout and open the customer.xml file. Here, all blocks are wrapped around main <layout> tag. You can see the different <tag> which contains specific blocks.

See the below snippet:

<!--
New customer registration
-->
 
    <customer_account_create translate="label">
        <label>Customer Account Registration Form</label>
        <!-- Mage_Customer -->
        <remove name="right"/>
        <remove name="left"/>
 
        <reference name="root">
            <action method="setTemplate"><template>page/1column.phtml</template></action>
        </reference>
        <reference name="content">
            <block type="customer/form_register" name="customer_form_register" template="customer/form/register.phtml">
                <block type="page/html_wrapper" name="customer.form.register.fields.before" as="form_fields_before" translate="label">
                    <label>Form Fields Before</label>
                </block>
            </block>
        </reference>
    </customer_account_create>

Handle

Handles are the main entity through which Magento identifies which block to load when a particular module is being called. <customer_account_create> is the module-specific handle. This handle is being triggered when someone opens the customer registration page.

Each handles content-nested block specific to the page. Some of layouts files contain the <default> handle. At this stage, you may ask about the difference between module specific-handles and default handles. In short, module-specific handles only render the blocks inside it when that module is being rendered in browser whereas default handle loads in most of the page.

<block>

Inside the handle there is the different different blocks which specify the template file to be render when that block is being called. Blocks are of two types:

Structurer Blocks
Content Blocks

In our layout file we are defining only the Content Blocks and then we wrap them in Structurer Blocks. For example, if someone is calling a customer registration page and we want to load it on left, right, content, or footer, we wrap that block in its respective structurer block. Here, we have wrapped two blocks inside the "content" block which is a structurer block.

Blocks contains attributes like following:

type defines the block classes in which we can define the different functionality
name defines the unique name of particular block so the other blocks can make a reference of existing block by name and extend it
before/after are attributes that we can set that allow us to define the position of our block inside structurer block
template defines the actual phtml file name and path where our HTML and PHP code goes
action allows us to trigger any action like loading JavaScript and all by using this attribute.
as is an attribute is mainly used for structurer blocks

<reference>

The <reference> tag is use to extend the blocks that already exist. In this case, we have extended the content block and inserted our own block into it. You must use the correct block name that you want to extend.

<remove>

The <remove> tag is use to remove the specific block. For example, say that on your account registration page you, don't want to display the right and left columns. In that case, then you can simply remove that block with the following syntax <remove name="your block name">.

Child <block>

When you wrap one block under another block, that wrapped block is called child block. Whenever our parent block is called by our module, the child block is automatically called.

<block type='core/template' name='parent' template='parent.phtml'>
<block type='core/template' name='child' template='child.phtml'/>
</block>

You can call child block separately too with below syntax in you template file
echo $this->getChildHtml(‘child');

root <block>

Open page.xml layout file, you will find the <root> block that is looks like below

<block type="page/html" name="root" output="toHtml" template="page/3columns.phtml">

Magento starts rendering from the root block. All other blocks are child blocks of the root block. The root block defines the structure of the page. Here, you can see that currently it's set to 3columns.phtml, you can change this to 1column.phtml, 2columns-right.phtml or 2columns-left.phtml.

Adding CSS and JavaScript to the Layout XML

For any particular page you can add CSS and JavaScript files into layout tag like this:

<customer_account_create>
 <reference name='head'>
  <action method="addCss"><stylesheet>css/styles.css</stylesheet></action>
  <action method="addJs"><script>varien/js.js</script></action>
 </reference>
</customer_account_create>

Here you can see that we have added a CSS file and a JavaScript file inside the head of our customer account page.

What Are The Block Classes?

Block classes are use to define the functions that are specific to particular block. Block classes file are resides in app > code > local/community/core > your module namespace > your module name > Block directory. These file contains the functions which we can use directly with $this keyword in block specific template file. Let's take one example to understand the block classes.

Go to review.xml file that is resides in app > design > frontend > base > default > layout directory and find the below line of code:

<!--
Customer account home dashboard layout
-->
 
    <customer_account_index>
 
        <!-- Mage_Review -->
        <reference name="customer_account_dashboard">
            <block type="review/customer_recent" name="customer_account_dashboard_info1" as="info1" template="review/customer/recent.phtml"/>
        </reference>
 
</customer_account_index>

Here you can see the block review/customer_recent that refer to the template recent.phtml. Go to app > design > frontend > base > default > template > review > customer and open recent.phtml.

In this file, you can see two functions being called using $this keyword. They are $this->getCollection() and $this->count(). These functions are defined in their block classes file recent.php that resides in app > code > core > Mage > review > Block > customer directory.

Here, the block type = "review/customer_recent" refers to the Mage_Review_Block_Customer_Recent block class that is define in recent.php file. Whatever functions you define in this class, you can directly use it in corresponding template file with $this.

Creating Custom Module Layout and Block Files

Lastly, we were left with custom "Hello World" module with controller. Here, we create the layout file of our custom module.so let's create it.

To create the layout file, we need to first create the block class file. Before we add the class file, we need to tell our module that we are including the block files. So go to app > code > local > Chiragdodia > Mymodule > etc > config.xml and add the below line of code:

<frontend>
<layout>
        <updates>
            <mymodule>
                <file>mymodule.xml</file> <!-- Our layout file name-->
            </mymodule>
        </updates>
</layout>
</frontend>
<global>
        <blocks>
            <mymodule>
                <class>Chiragdodia_Mymodule_Block</class>
            </mymodule>
        </blocks>
</global>

The final XML file contains the following lines of code:

<?xml version="1.0"?>
<config>
    <modules>
        <Chiragdodia_Mymodule>
            <version>0.1.0</version>    <!-- Version of module -->
        </Chiragdodia_Mymodule>
    </modules>
    <frontend>
        <routers>
            <mymodule>
                <use>standard</use>
                <args>
                    <module>Chiragdodia_Mymodule</module>
                    <frontName>mymodule</frontName>
                </args>
            </mymodule>
        </routers>
         <layout>
            <updates>
                <mymodule>
                    <file>mymodule.xml</file> <!-- Our layout file name-->
                </mymodule>
            </updates>
         </layout>
    </frontend>
    <global>
        <blocks>
            <mymodule>
                <class>Chiragdodia_Mymodule_Block</class>
            </mymodule>
        </blocks>
    </global>
</config>

Create the Block Class File

Next, go to app > code > local > Chiragdodia > Mymodule > Block and create the file Mymodule.php that contains below lines of code

<?php
class Chiragdodia_Mymodule_Block_Mymodule extends Mage_Core_Block_Template
{
    public function myfunction()
    {
        return "Hello tuts+ world";
    }
}

Here we have declared the class Chiragdodia_Mymodule_Block_Mymodule that contains the function myfunction which we can call directly from our layout template file.

Create the Layout XML File

Go to app > design > frontend > default > default > layout and create the mymodule.xml file which contains below lines of code

<?xml version="1.0"?>
<layout version="0.1.0">
    <mymodule_index_index>
        <reference name="content">
            <block type="mymodule/mymodule" name="mymodule" template="mymodule/mymodule.phtml" />
        </reference>
    </mymodule_index_index>
</layout>

Create the Template File

Go to app > design > frontend > default > default > template and create the mymodule.phtml file. In this file, we will call the function myfunction that we have declared in our block class.

<?php
    echo $this->myfunction();
?>

If everything is correct thus far, you will see the output with three columns layout by accessing the URL yoursite.com/index.php/mymodule/index.

In some Magento versions, default themes do not contain the layout and template directories. In that case you can create your layout and template file in app > design > frontend > base directory.

This is how layouts work in Magento. In the previous article, we created the simple "Hello World" module, in this article we have created it using layout file. The Magento layout structure is little bit difficult to understand at first, but once you begin tinkering with it, you will easily get the idea behind it.

In this post, I have attached the module demo files that we have created till now. Feel free to comment and ask any questions that you may have about this particular issue.

http://code.tutsplus.com/tutorials/custom-layouts-and-templates-with-magento--cms-21419