探析magento的Layout xml Part 1

在Magento的MVC模式中的View层被分为2个部分：Layout 和Template。Template 是在layout中定义的在页面的具体什么位置显示的html。Magento 提供了十分简便，灵活的xml的配置。1 Layout XML layout的xml能在系统的app/design/frontend/[package]/[theme]/layout中找到。每个Ma

yhuan_

1439人浏览 · 2012-11-09 15:35:11

yhuan_ · 2012-11-09 15:35:11 发布

在Magento的MVC模式中的View层被分为2个部分：Layout 和Template。Template 是在layout中定义的在页面的具体什么位置显示的html。Magento 提供了十分简便，灵活的xml的配置。

1 Layout XML

layout的xml能在系统的app/design/frontend/[package]/[theme]/layout中找到。每个Magento的模块都可以在自己模块的/etc/config.xml中定义自己的layout的xml文件。

<frontend>
  <layout>
    <updates>
      <mymodule>
        <file>mymodule.xml</file>
      </mymodule>
    </updates>
  </layout>
</frontend>

呈现页面前，magento将把所有的xml都加载成一个xml树，来确定每个block呈现在页面的具体位置。

下面来看下Mage_Contacts模块的contacts.xml文件，xml的根元素都是<layout>。

<layout version="0.1.0">
  <default>
    <reference name="footer_links">
      <action method="addLink" translate="label title" module="contacts" ifconfig="contacts/contacts/enabled"><label>Contact Us</label><url>contacts</url><title>Contact Us</title><prepare>true</prepare></action>
    </reference>
  </default>
 
  <contacts_index_index translate="label">
    <label>Contact Us Form</label>
    <reference name="root">
      <action method="setTemplate"><template>page/2columns-right.phtml</template></action>
      <action method="setHeaderTitle" translate="title" module="contacts"><title>Contact Us</title></action>
    </reference>
    <reference name="content">
      <block type="core/template" name="contactForm" template="contacts/form.phtml"/>
    </reference>
  </contacts_index_index>
</layout>

2 Layout Handles

在<layout>节点下的第一层节点元素叫做Layout Handles。每个Layout Handles代表来一个页面layout的更新。它可能在页面中新加入一个block或者删除一些block，也可以定义修改以及存在在页面里的layout中的block。

在magento加载好所有的xml后，它会决定在一个页面中哪些Layout Handles需要处理。通常，Layout Handles是由controller action 来决定执行的。在大多数情况下，magentolayout handle的名字是这样的：[module_front_name]_[controller_name]_[action_name].

当我们使用Mage_Contacts模块的index控制器的index方法来请求contact us页面时，模块名是contacts,所以contact us页面的layout handle是contacts_index_index.

在任何页面，magento总是会处理default的layout handle。所有更新定义在default中的layout handle将作用于网站的所有页面。在上面的例子中的具体元素将在下一节介绍。

3 Layout Elements

label：这个元素在magento1.4引进。它定义了Handles的标识。
reference:这个元素用来连接已经存在在xml中的任意的block。用来增加子block到已经存在的block中，改变已存在block的属性，增加action到已存在block。这个元素必须有个name属性来连接已存在的block。
block ：这个元素用来创建新的block。当我们想创建一个新的block时，该元素常用来在reference元素中创建新的block。block元素必须要有一个name属性（layout中的唯一标识）和一个type属性（用来定义block的类名）。如果这个block的type属性是core/template类型或他的子类型，它可以有个template属性来定义作用于这个block的phtml文件。
remove：这个元素用来删除block，通过name属性。
action：这个元素被定义在新建的block或者referenced的block中。每一个action是block的一个简单的实例化，method属性定义了在这个实例中的方法名。Action元素的所有的子元素可以看成是这个方法的参数。
```
<action method="setTemplate"><template>page/2columns-right.phtml</template></action>
```
译者注：可以看做是：
```
$this-> setTemplate('page/2columns-right.phtml')
```
update:这个元素用来把一个已经存在的layout handle加载到现在 layout handle中。它必须有一个handle属性用来定义包含进来的layout handle。

eg：在所有的用户帐号页面有一块相同的layout（页面上就是tab），当页面刷新时，出现的是同一个。我们可以在customer.xml定义一个layout handle: customer_account来统一调用他，而不是为每个页面定义一次这个相同的handle。

<customer_account translate="label">
  <label>Customer My Account (All Pages)</label>
  <!-- Mage_Customer -->
  <reference name="root">
    <action method="setTemplate"><template>page/2columns-left.phtml</template></action>
  </reference>
 
  <reference name="content">
    <block type="page/html_wrapper" name="my.account.wrapper">
      <action method="setElementClass"><value>my-account</value></action>
    </block>
  </reference>
 
  <reference name="left">
    <block type="customer/account_navigation" name="customer_account_navigation" before="-" template="customer/account/navigation.phtml">
      <action method="addLink" translate="label" module="customer"><name>account</name><path>customer/account/</path><label>Account Dashboard</label></action>
      <action method="addLink" translate="label" module="customer"><name>account_edit</name><path>customer/account/edit/</path><label>Account Information</label></action>
      <action method="addLink" translate="label" module="customer"><name>address_book</name><path>customer/address/</path><label>Address Book</label></action>
    </block>
    <block type="catalog/product_compare_sidebar" name="catalog.compare.sidebar" template="catalog/product/compare/sidebar.phtml"/>
    <block type="sales/reorder_sidebar" name="sale.reorder.sidebar" as="reorder" template="sales/reorder/sidebar.phtml"/>
    <remove name="tags_popular"/>
  </reference>
</customer_account>

下面是在customer.xml中的address page handle的例子。当点击address page时，上面的handle也将被加载进来。

<customer_address_index translate="label">
  <label>Customer My Account Address Book</label>
  <!-- Mage_Customer -->
  <update handle="customer_account"/>
  <reference name="my.account.wrapper">
    <block type="customer/address_book" name="address_book" before="-" template="customer/address/book.phtml"/>
  </reference>
</customer_address_index>

所以当请求customer address页面时，customer_account也将加载到页面中。
注：使用了update来引入customer_account。

4 Rendering Process（加载过程）

在呈现页面前，所有在layout中定义的block将被实例化。在block块中的block被定义为子block。当任何的block元素定义了一个output属性，那么它将没当作是一个输出的block。只有output的block能被呈现和增加到响应。所有的子block只有在他们被父block调用时，才会呈现。

在magento默认的theme中，root block被定义为output block。这个block被定义在page.xml中。当呈现这个block时，这个block的template属性定义了一些template页面：1 column, 2 columns with left sidebar, 2 columns with right sidebar, 3 columns 等等。默认情况下，页面将呈现3 columns 页面。同时在root blcok 下也定义了一些个子block ：head,header,breadcrumbs, left, right, content, footer 等等。这些子block在3columns.phtml可以这样被调用：

echo $this->getChildHtml('header');

在任何的template中，这些子block可以通过像上面那样的getChildHtml() 来被调用，它的第一个参数是子block的名字。当它没有参数时，它将在当前block中调用所有定义过的子block。

所以说，magento的布局是也个递归的过程，先是root，再是它的子block，再是子block的子block。

5 Putting it all together

在看下contacts.xml文件的例子。这个layout的更新文件是增加一个 contact us页面的连接（contact us页面设置为有效的）。
在page.xml中已经定义过一个footer_links block用来显示page footer的连接。在这个block中存在一个addLink方法来增加新的连接。所以，已经存在的footer_links block能增加连接，并把一些参数存进去。

<default>
  <reference name="footer_links">
    <action method="addLink" translate="label title" module="contacts" ifconfig="contacts/contacts/enabled"><label>Contact Us</label><url>contacts</url><title>Contact Us</title><prepare>true</prepare></action>
  </reference>
</default>

在上面的例子中，method属性的addLink方法能把参数（label,url,title等）传递过去。translate属性定义了在传参数时，哪些参数需要被翻译。上面的例子label和title可以通过现在locale来翻译。ifconfig属性定义了系统的配置的key，value的值通常只有yes/no。
如果value是no的话，那么contact us页面将不显示。Ifconfig属性只能在action元素中出现。

<contacts_index_index translate="label">
  <label>Contact Us Form</label>
  <reference name="root">
    <action method="setTemplate"><template>page/2columns-right.phtml</template></action>
    <action method="setHeaderTitle" translate="title" module="contacts"><title>Contact Us</title></action>
  </reference>
  <reference name="content">
    <block type="core/template" name="contactForm" template="contacts/form.phtml"/>
  </reference>
</contacts_index_index>

上面已经说了，magento将自动决定在当前的action中加载哪个handle。在上面的例子中，将调用Mage_Contacts模块的Index控制器和 index方法。Mage_Contacts的front name是contacts，所以它的handle是contacts_index_index。label的标记是Contact Us Form，可以用来区分在后台页面上的同一区域。

我们可以在admin的cms->Widgets中看到下图。

6 Block Types

core/template：这个block靠它的template属性来呈现template。
page/html： core/template的子type，定义了root block。所有的block都是它的子block。
page/html_head：定义了page的html head，包含js,css。
page/html_header:定义了page的header，包含网站logo，top links等。
page/template_links：用来创建link的列表。
core/text_list：像content, left, right这些block，都是属于core/text_list的。当这些block调用rendered时，它所有的子block将自动呈现，而不用每个调用getChildHtml()方法。
page/html_wrapper：这个block用来创建一个wrapper block，可以通过setHtmlTagName方法来呈现在html_tag的子block。如果没有任何元素设置，那么默认标签是<div>.
page/html_breadcrumbs：顾名思义。
page/html_footer：顾名思义。
core/messages : 呈现error/success/notice信息。
page/switch: 用来选择store 或者 language 。