Inside Layout XML

Block

A basic layout block looks like

<block class="\Some\Block" name="topnav" template="template.page.html.topmenu">
</block>

Here

1. class = Php file where all functions used in template.page.html.topmenu are location. This is the block class. For eg. In the current case it is \Some\Block. All the block class must be a instance of \Layout\Core\Block

2. name = any unique name given for the block

3. template = path of the view file used

In the template file, we using various php function $block object. The $block object is basically the object of the block type we defined. To see the significance of block type , open the file /path/to/project/vendor/sunel/laravel-layout/views/template/page/html/topmenu.blade.php There you will find a code.

{? $items = $block->getMenus() ?}

So the function $block->getMenus() is a class function, which is defined in class \Some\Block. So if block type is wrong, then a block doesn’t work.

Child Block

Put one block tag inside another to make a child block.

 <block class="\Some\Block" name="parent" as="parent" template="parent">
      <block class="\Some\Block" name="child.1" as="child.1" template="child.1">
         <block class="\Some\Block" name="child.1.1" as="child.1.1" template="child.1.1">
      </block>
      <block class="\Some\Block" name="child.2" as="child.2" template="child.2">
 </block>

In the view file parent.blade.php you can access the child block by

   {!! $block->getChildHtml('child.1') !!}
   {!! $block->getChildHtml('child.2') !!}

In the view file child.1.blade.php you can access the child block by

   {!! $block->getChildHtml('child.1.1') !!}

$block->getChildHtml() function, it is basically used to the get the content of the its child block.

Making child blocks, divides your view logic into separate files, and make reading of code simpler.

Default

  <default>
    ...
  </default>

The default tag means, all blocks inside this tag are to be shown in all the pages. So blocks like header, footer, menu etc are placed inside tag, so that they are shown in all pages.

The Root Block and Default Root Templates

Few different type of page structures.

• 1 column layout - template/page/1column.blade.php
• 2 column left - template/page/2columns-left.blade.php
• 2 column right - template/page/2columns-right.blade.php
• 3 column layout - template/page/3columns.blade.php
• empty layout - template/page/empty.blade.php

In these files you will see HTML skeleton structure which has divided the page into header, footer, left column, right column, main body etc, these files make the basic skeleton of the pages. You will find many

   {!! $block->getChildHtml() !!}

function in these templates.

default.xml layout file, also contains an important block i.e the root block. This block is defined inside the tag as

<block class="\Layout\Page\Html" name="root" output="toHtml" template="render::template.page.3columns">
  ...
</block>

The root block is like the top most parent block, this block defines the structure of a page and all other block comes as children of the root block.

So, suppose if you want to set the structure of a page as 1column, then do the below inside the page handler tag.

 <reference name="root">
   <action method="setTemplate"><template>render::template.page.1column</template></action>
 </reference>

Basically, this calls a function setTemplate in the root block. For example if you want the application login page to have 2columns-left layout. Then you need to do this

<user_login>
  <reference name="root">
     <action method="setTemplate">
           <template>render::template.page.2columns-left</template>      
     </action>
  </reference>
</user_login>

There are few blocks which are important in the system layout and widely used. For example**, the content block, left, right, head (these are block name),** all these blocks are defined in default.xml.

• Content block is used to display the main content area.
• Left and Right are used in 2column-left layout and 2column-right layout respectively.
• Head is used to add css, javascript and other html tag related work.

The important thing to know about these blocks is that, which ever child you add to these block, they automatically get displayed in them. You don’t need to call getChildHtml('childname') for these blocks.

Reference

As we know now layout is divided in many xml files. But there are many blocks that we want to use, lets say we have a user module and it has layout xml user.xml and we need to add a user profile details on left side, but it is defined in a different file like default.xml. For example the head, content, root block are all defined in default.xml but we want to use them in other layout files as well. To do this, we have a tag <reference> tag. Using this tag, we can take a reference of another block and add child elements to it or do other operations on it. For example, if I want to add a block in the left column as said from the user.xml file. we do this

<reference name='left'>
    <block type='\Your\Block' name='somename' template='your.template' />
</reference>

Action

Now you would have come across the <action> tag and must have a some idea, So basically the action tag calls the method that is been defined in the block class that it has been refereed too. The parameter are added as child nodes.

 <reference name="root">
     <action method="setTemplate">
           <template>render::template.page.2columns-left</template>      
     </action>
  </reference>

Page Handler

They are used to display block specific to pages. Like if we want to place a block on the user account page or registration page then we use such tags. These tags are based on the router handle of the URL.

So the layout tag for user account page would be <user_account>

<user_account>
  <reference name="root">
     <action method="setTemplate">
           <template>render::template.page.2columns-left</template>      
     </action>
  </reference>
  <reference name='content'>
      <block type='\Your\Block' name='somename' template='your.template' />
  </reference>
  <reference name='left'>
      <block type='\Your\Block' name='somename' template='your.template' />
  </reference> 
</user_account>

So the layout tag for user account edit page would be <user_account_edit>

<user_account_edit>
  <reference name="root">
     <action method="setTemplate">
           <template>render::template.page.2columns-left</template>      
     </action>
  </reference>
  <reference name='content'>
      <block type='\Your\Block' name='somename' template='your.template' />
  </reference>
  <reference name='left'>
      <block type='\Your\Block' name='somename' template='your.template' />
  </reference> 
</user_account_edit>

The blocks inside such tags are read on those pages and not other pages.