Layout and Template API

This document provides a reference for the programmatic API used to manipulate layouts, create blocks, and render templates in Maho. It documents the methods available in Mage_Core_Model_Layout, Mage_Core_Block_Abstract, and related classes.

For architectural overview of the layout system, see section 3.4. For frontend-specific layout XML usage, see section 6.2. For block lifecycle details, see section 14.3.

Mage_Core_Model_Layout

The Mage_Core_Model_Layout class (app/code/core/Mage/Core/Model/Layout.php13) is the central interface for layout operations. Controllers and blocks access it via $this->getLayout(). It extends Maho\Simplexml\Config to handle the merged layout XML structure.

Core Layout Methods

Method	Parameters	Return Type	Purpose
getUpdate()	none	Mage_Core_Model_Layout_Update	Returns the layout update object for handle management app/code/core/Mage/Core/Model/Layout.php81-84
setArea($area)	string $area	$this	Set layout area (e.g., 'frontend', 'adminhtml') app/code/core/Mage/Core/Model/Layout.php92-96
getArea()	none	string	Get current layout area app/code/core/Mage/Core/Model/Layout.php103-106
generateXml()	none	$this	Process layout XML, applying <remove> directives and ACL checks app/code/core/Mage/Core/Model/Layout.php135-169
generateBlocks($parent)	Mage_Core_Model_Layout_Element|\Maho\Simplexml\Element|null	void	Recursively create block hierarchy from XML structure app/code/core/Mage/Core/Model/Layout.php177-202
createBlock($type, $name, $attributes)	string|object, string, array	Mage_Core_Block_Abstract|false	Factory method to instantiate and register blocks app/code/core/Mage/Core/Model/Layout.php422-451
addBlock($block, $blockName)	string|object, string	Mage_Core_Block_Abstract	Alias for createBlock() app/code/core/Mage/Core/Model/Layout.php411-414
getBlock($name)	string	Mage_Core_Block_Abstract|false	Retrieve block instance by name from registry app/code/core/Mage/Core/Model/Layout.php549-552
getAllBlocks()	none	array<Mage_Core_Block_Abstract>	Get all registered blocks as array app/code/core/Mage/Core/Model/Layout.php540-543
setBlock($name, $block)	string, object	$this	Register block in _blocks array app/code/core/Mage/Core/Model/Layout.php514-518
unsetBlock($name)	string	$this	Remove block from _blocks registry app/code/core/Mage/Core/Model/Layout.php526-533
getBlockSingleton($type)	string	Mage_Core_Block_Abstract|stdClass	Get or create singleton block instance (cached in _helpers) app/code/core/Mage/Core/Model/Layout.php567-581
addOutputBlock($blockName, $method)	string, string	$this	Register block for automatic output (stored in _output array) app/code/core/Mage/Core/Model/Layout.php590-594
removeOutputBlock($blockName)	string	$this	Remove block from output registry app/code/core/Mage/Core/Model/Layout.php602-606
getOutput()	none	string	Render all registered output blocks by calling their methods app/code/core/Mage/Core/Model/Layout.php613-628
helper($name)	string	Mage_Core_Helper_Abstract|false	Get helper instance (cached per layout in _helpers) app/code/core/Mage/Core/Model/Layout.php493-506
setDirectOutput($flag)	bool	$this	Set whether blocks output directly or return HTML app/code/core/Mage/Core/Model/Layout.php114-118
getDirectOutput()	none	bool	Get direct output flag app/code/core/Mage/Core/Model/Layout.php125-128

Sources: app/code/core/Mage/Core/Model/Layout.php13-628

Block Creation and Management

Title: Block Creation Flow in Mage_Core_Model_Layout

The createBlock() method at app/code/core/Mage/Core/Model/Layout.php422-451 performs block instantiation, configuration, and registration. Block class names are resolved via Mage::getConfig()->getBlockClassName() which maps type aliases like 'catalog/product_view' to class names like 'Mage_Catalog_Block_Product_View'.

Sources: app/code/core/Mage/Core/Model/Layout.php422-451 app/code/core/Mage/Core/Model/Layout.php472-484

Block Hierarchy Construction

Title: Layout XML Processing in generateBlocks()

The generateBlocks() method at app/code/core/Mage/Core/Model/Layout.php177-202 recursively processes layout XML. For <block> nodes, _generateBlock() at app/code/core/Mage/Core/Model/Layout.php211-265 creates blocks and manages parent-child relationships. For <action> nodes, _generateAction() at app/code/core/Mage/Core/Model/Layout.php272-341 executes block methods with parameters parsed from XML.

Sources: app/code/core/Mage/Core/Model/Layout.php177-202 app/code/core/Mage/Core/Model/Layout.php211-265 app/code/core/Mage/Core/Model/Layout.php272-341

Mage_Core_Block_Abstract

The Mage_Core_Block_Abstract class (app/code/core/Mage/Core/Block/Abstract.php33) is the base class for all blocks. It provides methods for child block management, rendering, and layout interaction. It inherits from Maho\DataObject for flexible data handling.

Block Property Management

Method	Parameters	Return Type	Purpose
setLayout($layout)	Mage_Core_Model_Layout	$this	Set layout instance and trigger _prepareLayout() app/code/core/Mage/Core/Block/Abstract.php292-299
getLayout()	none	Mage_Core_Model_Layout	Get layout instance from _layout property app/code/core/Mage/Core/Block/Abstract.php311-314
setNameInLayout($name)	string	$this	Set block name in _nameInLayout and update layout registry app/code/core/Mage/Core/Block/Abstract.php346-353
getNameInLayout()	none	string	Get block name from _nameInLayout app/code/core/Mage/Core/Block/Abstract.php360-363
setBlockAlias($alias)	string	$this	Set alias used by parent (stored in _alias) app/code/core/Mage/Core/Block/Abstract.php390-394
getBlockAlias()	none	string	Get block alias app/code/core/Mage/Core/Block/Abstract.php401-404
setParentBlock($block)	Mage_Core_Block_Abstract	$this	Set parent block reference in _parentBlock app/code/core/Mage/Core/Block/Abstract.php271-275
getParentBlock()	none	Mage_Core_Block_Abstract|null	Get parent block app/code/core/Mage/Core/Block/Abstract.php261-264

Sources: app/code/core/Mage/Core/Block/Abstract.php261-404

Block Rendering Flow

Title: Block Rendering Pipeline in toHtml()

The toHtml() method at app/code/core/Mage/Core/Block/Abstract.php901-946 is final and implements a fixed rendering pipeline. Subclasses override the protected _toHtml() method to provide actual HTML generation. The method checks module output configuration via Mage_Core_Helper_Abstract::isModuleOutputEnabled() app/code/core/Mage/Core/Helper/Abstract.php120-131 manages block HTML caching, and uses a shared Maho\DataObject instance for event transport to avoid object creation overhead app/code/core/Mage/Core/Block/Abstract.php162

Sources: app/code/core/Mage/Core/Block/Abstract.php901-946 app/code/core/Mage/Core/Helper/Abstract.php120-131

Layout Action Methods

Layout <action> elements execute block methods with parameters parsed from XML. The _generateAction() method at app/code/core/Mage/Core/Model/Layout.php272-341 processes these elements.

Title: Layout Action Parameter Processing in _generateAction()

The _generateAction() method performs conditional execution via ifconfig, resolves helper callbacks, converts XML structures to arrays, decodes JSON parameters, translates strings, validates security, and executes the block method. Parameter conversion supports the helper attribute for calling helper methods and the json attribute for JSON decoding specific parameters.

Sources: app/code/core/Mage/Core/Model/Layout.php272-341 app/code/core/Mage/Core/Model/Layout.php349-387

Template Rendering

Templates are .phtml files executed in the context of Mage_Core_Block_Template instances. Within templates, $this refers to the block instance.

Template Variable Access

Templates access data through block methods:

Variable Access	Underlying Method	Purpose
$this->getData('key')	Maho\DataObject::getData()	Access block data app/code/core/Mage/Core/Block/Abstract.php33
$this->helper('module')	Mage_Core_Block_Abstract::helper()	Get helper instance app/code/core/Mage/Core/Block/Abstract.php1095-1108
$this->__('String', ...)	Mage_Core_Block_Abstract::__()	Translate string app/code/core/Mage/Core/Block/Abstract.php1117-1122
$this->getUrl($route, $params)	Mage_Core_Block_Abstract::getUrl()	Generate URL app/code/core/Mage/Core/Block/Abstract.php1157-1160
$this->getChildHtml('alias')	Mage_Core_Block_Abstract::getChildHtml()	Render child block app/code/core/Mage/Core/Block/Abstract.php576-608
$this->escapeHtml($data)	Mage_Core_Block_Abstract::escapeHtml()	HTML-escape data app/code/core/Mage/Core/Block/Abstract.php1134-1137

Sources: app/code/core/Mage/Core/Block/Abstract.php576-1160

Block Caching

Blocks support automatic caching by setting data properties. Cache keys are prefixed with BLOCK_ (app/code/core/Mage/Core/Block/Abstract.php38) and use the block_html cache tag (app/code/core/Mage/Core/Block/Abstract.php42).

Property	Type	Purpose
cache_lifetime	int|false	Cache duration in seconds app/code/core/Mage/Core/Block/Abstract.php21
cache_key	string	Unique identifier for this block app/code/core/Mage/Core/Block/Abstract.php22
cache_tags	array	Cache tags for invalidation app/code/core/Mage/Core/Block/Abstract.php23

Sources: app/code/core/Mage/Core/Block/Abstract.php21-42

Helper API for Layouts

Helpers provide utility methods for templates and layout XML. Mage_Core_Helper_Abstract provides foundational methods:

• HTML Escaping: escapeHtml() app/code/core/Mage/Core/Helper/Abstract.php180-203 and escapeUrl() app/code/core/Mage/Core/Helper/Abstract.php247-254 ensure secure output. Specific helpers like Mage_Adminhtml_Helper_Sales override escapeHtml() to provide additional functionality, such as escapeHtmlWithLinks() app/code/core/Mage/Adminhtml/Helper/Sales.php108-143 which preserves links.
• Module Status: isModuleOutputEnabled() app/code/core/Mage/Core/Helper/Abstract.php120-131 allows layout logic to skip blocks from disabled modules.
• Translation: __() app/code/core/Mage/Core/Helper/Abstract.php165-171 handles string localization using the helper's module name.

Sources: app/code/core/Mage/Core/Helper/Abstract.php120-254 app/code/core/Mage/Adminhtml/Helper/Sales.php108-143