 |
VOOZH | about |
|
VOOZH | about |
This document provides a technical reference for the Block API in Maho, which handles presentation logic and HTML rendering. Blocks serve as the view layer in Maho's MVC architecture, bridging business logic from models with HTML output through templates. The base class Mage_Core_Block_Abstract defines the rendering lifecycle, child management, and caching mechanisms used throughout the platform.
For information about Layout XML and block tree construction, see Layout and Template API For frontend theme architecture, see Theme Architecture
All blocks in Maho extend from Mage_Core_Block_Abstract, which provides core functionality for the block system. This base class itself extends \Maho\DataObject to provide flexible data storage and accessors.
Core Block Inheritance Structure:
Sources: app/code/core/Mage/Core/Block/Abstract.php33-34 app/code/core/Mage/Adminhtml/Block/Template.php13 app/code/core/Mage/Adminhtml/Block/Widget.php19-20 app/code/core/Mage/Adminhtml/Block/Sales/Order/View/History.php13 app/code/core/Mage/Adminhtml/Block/Sales/Order/Comments/View.php13
The Mage_Core_Block_Abstract class maintains several critical properties for identifying and organizing blocks within the layout tree:
| Property | Type | Description |
|---|---|---|
$_nameInLayout | string | Unique identifier for block in layout tree. app/code/core/Mage/Core/Block/Abstract.php54 |
$_layout | Mage_Core_Model_Layout | Reference to parent layout instance. app/code/core/Mage/Core/Block/Abstract.php61 |
$_parent | Mage_Core_Block_Abstract | Parent block in hierarchy. app/code/core/Mage/Core/Block/Abstract.php68 |
$_parentBlock | Mage_Core_Block_Abstract | Alternative parent reference used for internal traversal. app/code/core/Mage/Core/Block/Abstract.php138 |
$_alias | string | Short alias used by parent to reference this block. app/code/core/Mage/Core/Block/Abstract.php75 |
$_children | array | Child blocks indexed by alias. app/code/core/Mage/Core/Block/Abstract.php89 |
$_sortedChildren | array | Ordered list of child block names. app/code/core/Mage/Core/Block/Abstract.php96 |
$_isAnonymous | bool | Whether block was auto-named. app/code/core/Mage/Core/Block/Abstract.php131 |
Sources: app/code/core/Mage/Core/Block/Abstract.php50-170
The rendering process follows a strict sequence of preparation, rendering, and post-processing.
Key Lifecycle Methods:
| Method | Purpose | Override Recommendation |
|---|---|---|
__construct() | Object initialization and dependency injection for _factory and _app. app/code/core/Mage/Core/Block/Abstract.php195-205 | Rarely |
_construct() | Internal constructor for initialization logic. app/code/core/Mage/Core/Block/Abstract.php212-217 | Common |
setLayout() | Attaches block to layout; triggers _prepareLayout() and layout events. app/code/core/Mage/Core/Block/Abstract.php292-298 | No |
_prepareLayout() | Hook to configure block or add children after layout is set. app/code/core/Mage/Core/Block/Abstract.php296 | Common |
toHtml() | Main entry point for rendering. Handles caching logic. app/code/core/Mage/Core/Block/Abstract.php313-334 | No |
_beforeToHtml() | Pre-render hook to fetch data or validate state. app/code/core/Mage/Core/Block/Abstract.php341-344 | Common |
_toHtml() | Actual generation of HTML output. app/code/core/Mage/Core/Block/Abstract.php351-354 | Common |
Sources: app/code/core/Mage/Core/Block/Abstract.php195-354
Blocks are organized into a tree structure where parents manage the rendering of their children.
Core Management Methods:
setChild($alias, $block): Adds a child block. If alias is empty, an anonymous name is generated. app/code/core/Mage/Core/Block/Abstract.php430-469getChild($alias): Retrieves a child block by its alias. app/code/core/Mage/Core/Block/Abstract.php549-558getChildHtml($alias, $useCache, $sorted): Renders the child block. If alias is empty, it renders all children. app/code/core/Mage/Core/Block/Abstract.php572-602insert($block, $siblingName, $after, $alias): Inserts a block at a specific position relative to siblings. app/code/core/Mage/Core/Block/Abstract.php678-727Sources: app/code/core/Mage/Core/Block/Abstract.php430-727
Maho provides a granular fragment caching system for blocks to improve performance.
Cache Constants:
| Constant | Value | Purpose |
|---|---|---|
CACHE_KEY_PREFIX | 'BLOCK_' | Prefix for block cache keys. app/code/core/Mage/Core/Block/Abstract.php38 |
CACHE_GROUP | 'block_html' | The cache tag used for HTML blocks. app/code/core/Mage/Core/Block/Abstract.php42 |
Caching Logic:
The toHtml() method checks if getCacheLifetime() is set. If active, it attempts to load HTML from the cache using a key generated via getCacheKey(). If a miss occurs, the block renders and saves the result to the cache using getCacheTags(). app/code/core/Mage/Core/Block/Abstract.php313-334
Sources: app/code/core/Mage/Core/Block/Abstract.php36-47 app/code/core/Mage/Core/Block/Abstract.php313-334
Maho provides robust mechanisms for escaping data within blocks to prevent XSS.
Escaping Methods:
escapeHtml($data, $allowedTags): The primary method for escaping HTML entities, defined in Mage_Core_Helper_Abstract. It can process strings or arrays. app/code/core/Mage/Core/Helper/Abstract.php180-203maliciousCodeFilter($html): An admin-specific filter used to remove script tags and other dangerous elements via Mage_Core_Model_Input_Filter_MaliciousCode. app/code/core/Mage/Adminhtml/Block/Template.php53-56Mage_Core_Model_Security_HtmlEscapedString: A specialized class that implements Stringable to ensure data is escaped only when converted to a string. app/code/core/Mage/Core/Model/Security/HtmlEscapedString.php13-41Adminhtml Sales Helpers:
The Mage_Adminhtml_Helper_Sales class provides specialized escaping that preserves safe links (e.g., in order history comments) while sanitizing the rest of the content via escapeHtmlWithLinks. app/code/core/Mage/Adminhtml/Helper/Sales.php108-143
Sources: app/code/core/Mage/Core/Helper/Abstract.php180-203 app/code/core/Mage/Adminhtml/Block/Template.php53-56 app/code/core/Mage/Core/Model/Security/HtmlEscapedString.php13-41 app/code/core/Mage/Adminhtml/Helper/Sales.php108-143
Blocks have built-in access to helper classes for data manipulation and translation.
helper($name): Retrieves a helper singleton via the layout instance. app/code/core/Mage/Core/Block/Abstract.php1002-1005__(): Translates a string using the block's translation helper. app/code/core/Mage/Core/Block/Abstract.php1022-1026getRequest(): Provides access to the HTTP request object via the front controller. app/code/core/Mage/Core/Block/Abstract.php245-254getAction(): Returns the current front controller action. app/code/core/Mage/Core/Block/Abstract.php282-285Sources: app/code/core/Mage/Core/Block/Abstract.php245-285 app/code/core/Mage/Core/Block/Abstract.php1002-1026