1: <?php
   2: /**
   3:  * Magento
   4:  *
   5:  * NOTICE OF LICENSE
   6:  *
   7:  * This source file is subject to the Open Software License (OSL 3.0)
   8:  * that is bundled with this package in the file LICENSE.txt.
   9:  * It is also available through the world-wide-web at this URL:
  10:  * http://opensource.org/licenses/osl-3.0.php
  11:  * If you did not receive a copy of the license and are unable to
  12:  * obtain it through the world-wide-web, please send an email
  13:  * to license@magentocommerce.com so we can send you a copy immediately.
  14:  *
  15:  * DISCLAIMER
  16:  *
  17:  * Do not edit or add to this file if you wish to upgrade Magento to newer
  18:  * versions in the future. If you wish to customize Magento for your
  19:  * needs please refer to http://www.magentocommerce.com for more information.
  20:  *
  21:  * @category    Mage
  22:  * @package     Mage_Core
  23:  * @copyright   Copyright (c) 2012 Magento Inc. (http://www.magentocommerce.com)
  24:  * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
  25:  */
  26: 
  27: 
  28: /**
  29:  * Base Content Block class
  30:  *
  31:  * For block generation you must define Data source class, data source class method,
  32:  * parameters array and block template
  33:  *
  34:  * @category   Mage
  35:  * @package    Mage_Core
  36:  * @author      Magento Core Team <core@magentocommerce.com>
  37:  */
  38: abstract class Mage_Core_Block_Abstract extends Varien_Object
  39: {
  40:     /**
  41:      * Cache group Tag
  42:      */
  43:     const CACHE_GROUP = 'block_html';
  44:     /**
  45:      * Block name in layout
  46:      *
  47:      * @var string
  48:      */
  49:     protected $_nameInLayout;
  50: 
  51:     /**
  52:      * Parent layout of the block
  53:      *
  54:      * @var Mage_Core_Model_Layout
  55:      */
  56:     protected $_layout;
  57: 
  58:     /**
  59:      * Parent block
  60:      *
  61:      * @var Mage_Core_Block_Abstract
  62:      */
  63:     protected $_parent;
  64: 
  65:     /**
  66:      * Short alias of this block that was refered from parent
  67:      *
  68:      * @var string
  69:      */
  70:     protected $_alias;
  71: 
  72:     /**
  73:      * Suffix for name of anonymous block
  74:      *
  75:      * @var string
  76:      */
  77:     protected $_anonSuffix;
  78: 
  79:     /**
  80:      * Contains references to child block objects
  81:      *
  82:      * @var array
  83:      */
  84:     protected $_children                    = array();
  85: 
  86:     /**
  87:      * Sorted children list
  88:      *
  89:      * @var array
  90:      */
  91:     protected $_sortedChildren              = array();
  92: 
  93:     /**
  94:      * Children blocks HTML cache array
  95:      *
  96:      * @var array
  97:      */
  98:     protected $_childrenHtmlCache           = array();
  99: 
 100:     /**
 101:      * Arbitrary groups of child blocks
 102:      *
 103:      * @var array
 104:      */
 105:     protected $_childGroups                 = array();
 106: 
 107:     /**
 108:      * Request object
 109:      *
 110:      * @var Zend_Controller_Request_Http
 111:      */
 112:     protected $_request;
 113: 
 114:     /**
 115:      * Messages block instance
 116:      *
 117:      * @var Mage_Core_Block_Messages
 118:      */
 119:     protected $_messagesBlock               = null;
 120: 
 121:     /**
 122:      * Whether this block was not explicitly named
 123:      *
 124:      * @var boolean
 125:      */
 126:     protected $_isAnonymous                 = false;
 127: 
 128:     /**
 129:      * Parent block
 130:      *
 131:      * @var Mage_Core_Block_Abstract
 132:      */
 133:     protected $_parentBlock;
 134: 
 135:     /**
 136:      * Block html frame open tag
 137:      * @var string
 138:      */
 139:     protected $_frameOpenTag;
 140: 
 141:     /**
 142:      * Block html frame close tag
 143:      * @var string
 144:      */
 145:     protected $_frameCloseTag;
 146: 
 147:     /**
 148:      * Url object
 149:      *
 150:      * @var Mage_Core_Model_Url
 151:      */
 152:     protected static $_urlModel;
 153: 
 154:     /**
 155:      * @var Varien_Object
 156:      */
 157:     private static $_transportObject;
 158: 
 159:     /**
 160:      * Array of block sort priority instructions
 161:      *
 162:      * @var array
 163:      */
 164:     protected $_sortInstructions = array();
 165: 
 166:     /**
 167:      * Internal constructor, that is called from real constructor
 168:      *
 169:      * Please override this one instead of overriding real __construct constructor
 170:      *
 171:      */
 172:     protected function _construct()
 173:     {
 174:         /**
 175:          * Please override this one instead of overriding real __construct constructor
 176:          */
 177:     }
 178: 
 179:     /**
 180:      * Retrieve request object
 181:      *
 182:      * @return Mage_Core_Controller_Request_Http
 183:      * @throws Exception
 184:      */
 185:     public function getRequest()
 186:     {
 187:         $controller = Mage::app()->getFrontController();
 188:         if ($controller) {
 189:             $this->_request = $controller->getRequest();
 190:         } else {
 191:             throw new Exception(Mage::helper('core')->__("Can't retrieve request object"));
 192:         }
 193:         return $this->_request;
 194:     }
 195: 
 196:     /**
 197:      * Retrieve parent block
 198:      *
 199:      * @return Mage_Core_Block_Abstract
 200:      */
 201:     public function getParentBlock()
 202:     {
 203:         return $this->_parentBlock;
 204:     }
 205: 
 206:     /**
 207:      * Set parent block
 208:      *
 209:      * @param   Mage_Core_Block_Abstract $block
 210:      * @return  Mage_Core_Block_Abstract
 211:      */
 212:     public function setParentBlock(Mage_Core_Block_Abstract $block)
 213:     {
 214:         $this->_parentBlock = $block;
 215:         return $this;
 216:     }
 217: 
 218:     /**
 219:      * Retrieve current action object
 220:      *
 221:      * @return Mage_Core_Controller_Varien_Action
 222:      */
 223:     public function getAction()
 224:     {
 225:         return Mage::app()->getFrontController()->getAction();
 226:     }
 227: 
 228:     /**
 229:      * Set layout object
 230:      *
 231:      * @param   Mage_Core_Model_Layout $layout
 232:      * @return  Mage_Core_Block_Abstract
 233:      */
 234:     public function setLayout(Mage_Core_Model_Layout $layout)
 235:     {
 236:         $this->_layout = $layout;
 237:         Mage::dispatchEvent('core_block_abstract_prepare_layout_before', array('block' => $this));
 238:         $this->_prepareLayout();
 239:         Mage::dispatchEvent('core_block_abstract_prepare_layout_after', array('block' => $this));
 240:         return $this;
 241:     }
 242: 
 243:     /**
 244:      * Preparing global layout
 245:      *
 246:      * You can redefine this method in child classes for changing layout
 247:      *
 248:      * @return Mage_Core_Block_Abstract
 249:      */
 250:     protected function _prepareLayout()
 251:     {
 252:         return $this;
 253:     }
 254: 
 255:     /**
 256:      * Retrieve layout object
 257:      *
 258:      * @return Mage_Core_Model_Layout
 259:      */
 260:     public function getLayout()
 261:     {
 262:         return $this->_layout;
 263:     }
 264: 
 265:     /**
 266:      * Check if block is using auto generated (Anonymous) name
 267:      * @return bool
 268:      */
 269:     public function getIsAnonymous()
 270:     {
 271:         return $this->_isAnonymous;
 272:     }
 273: 
 274:     /**
 275:      * Set the anonymous flag
 276:      *
 277:      * @param  bool $flag
 278:      * @return Mage_Core_Block_Abstract
 279:      */
 280:     public function setIsAnonymous($flag)
 281:     {
 282:         $this->_isAnonymous = (bool)$flag;
 283:         return $this;
 284:     }
 285: 
 286:     /**
 287:      * Returns anonymous block suffix
 288:      *
 289:      * @return string
 290:      */
 291:     public function getAnonSuffix()
 292:     {
 293:         return $this->_anonSuffix;
 294:     }
 295: 
 296:     /**
 297:      * Set anonymous suffix for current block
 298:      *
 299:      * @param string $suffix
 300:      * @return Mage_Core_Block_Abstract
 301:      */
 302:     public function setAnonSuffix($suffix)
 303:     {
 304:         $this->_anonSuffix = $suffix;
 305:         return $this;
 306:     }
 307: 
 308:     /**
 309:      * Returns block alias
 310:      *
 311:      * @return string
 312:      */
 313:     public function getBlockAlias()
 314:     {
 315:         return $this->_alias;
 316:     }
 317: 
 318:     /**
 319:      * Set block alias
 320:      *
 321:      * @param string $alias
 322:      * @return Mage_Core_Block_Abstract
 323:      */
 324:     public function setBlockAlias($alias)
 325:     {
 326:         $this->_alias = $alias;
 327:         return $this;
 328:     }
 329: 
 330:     /**
 331:      * Set block's name in layout and unsets previous link if such exists.
 332:      *
 333:      * @param string $name
 334:      * @return Mage_Core_Block_Abstract
 335:      */
 336:     public function setNameInLayout($name)
 337:     {
 338:         if (!empty($this->_nameInLayout) && $this->getLayout()) {
 339:             $this->getLayout()->unsetBlock($this->_nameInLayout)
 340:                 ->setBlock($name, $this);
 341:         }
 342:         $this->_nameInLayout = $name;
 343:         return $this;
 344:     }
 345: 
 346:     /**
 347:      * Retrieve sorted list of children.
 348:      *
 349:      * @return array
 350:      */
 351:     public function getSortedChildren()
 352:     {
 353:         $this->sortChildren();
 354:         return $this->_sortedChildren;
 355:     }
 356: 
 357:     /**
 358:      * Set block attribute value
 359:      *
 360:      * Wrapper for method "setData"
 361:      *
 362:      * @param   string $name
 363:      * @param   mixed $value
 364:      * @return  Mage_Core_Block_Abstract
 365:      */
 366:     public function setAttribute($name, $value = null)
 367:     {
 368:         return $this->setData($name, $value);
 369:     }
 370: 
 371:     /**
 372:      * Set child block
 373:      *
 374:      * @param   string $alias
 375:      * @param   Mage_Core_Block_Abstract $block
 376:      * @return  Mage_Core_Block_Abstract
 377:      */
 378:     public function setChild($alias, $block)
 379:     {
 380:         if (is_string($block)) {
 381:             $block = $this->getLayout()->getBlock($block);
 382:         }
 383:         if (!$block) {
 384:             return $this;
 385:         }
 386: 
 387:         if ($block->getIsAnonymous()) {
 388:             $suffix = $block->getAnonSuffix();
 389:             if (empty($suffix)) {
 390:                 $suffix = 'child' . sizeof($this->_children);
 391:             }
 392:             $blockName = $this->getNameInLayout() . '.' . $suffix;
 393: 
 394:             if ($this->getLayout()) {
 395:                 $this->getLayout()->unsetBlock($block->getNameInLayout())
 396:                     ->setBlock($blockName, $block);
 397:             }
 398: 
 399:             $block->setNameInLayout($blockName);
 400:             $block->setIsAnonymous(false);
 401: 
 402:             if (empty($alias)) {
 403:                 $alias = $blockName;
 404:             }
 405:         }
 406: 
 407:         $block->setParentBlock($this);
 408:         $block->setBlockAlias($alias);
 409:         $this->_children[$alias] = $block;
 410:         return $this;
 411:     }
 412: 
 413:     /**
 414:      * Unset child block
 415:      *
 416:      * @param  string $alias
 417:      * @return Mage_Core_Block_Abstract
 418:      */
 419:     public function unsetChild($alias)
 420:     {
 421:         if (isset($this->_children[$alias])) {
 422:             /** @var Mage_Core_Block_Abstract $block */
 423:             $block = $this->_children[$alias];
 424:             $name = $block->getNameInLayout();
 425:             unset($this->_children[$alias]);
 426:             $key = array_search($name, $this->_sortedChildren);
 427:             if ($key !== false) {
 428:                 unset($this->_sortedChildren[$key]);
 429:             }
 430:         }
 431: 
 432:         return $this;
 433:     }
 434: 
 435:     /**
 436:      * Call a child and unset it, if callback matched result
 437:      *
 438:      * $params will pass to child callback
 439:      * $params may be array, if called from layout with elements with same name, for example:
 440:      * ...<foo>value_1</foo><foo>value_2</foo><foo>value_3</foo>
 441:      *
 442:      * Or, if called like this:
 443:      * ...<foo>value_1</foo><bar>value_2</bar><baz>value_3</baz>
 444:      * - then it will be $params1, $params2, $params3
 445:      *
 446:      * It is no difference anyway, because they will be transformed in appropriate way.
 447:      *
 448:      * @param string $alias
 449:      * @param string $callback
 450:      * @param mixed $result
 451:      * @param array $params
 452:      * @return Mage_Core_Block_Abstract
 453:      */
 454:     public function unsetCallChild($alias, $callback, $result, $params)
 455:     {
 456:         $child = $this->getChild($alias);
 457:         if ($child) {
 458:             $args     = func_get_args();
 459:             $alias    = array_shift($args);
 460:             $callback = array_shift($args);
 461:             $result   = (string)array_shift($args);
 462:             if (!is_array($params)) {
 463:                 $params = $args;
 464:             }
 465: 
 466:             if ($result == call_user_func_array(array(&$child, $callback), $params)) {
 467:                 $this->unsetChild($alias);
 468:             }
 469:         }
 470:         return $this;
 471:     }
 472: 
 473:     /**
 474:      * Unset all children blocks
 475:      *
 476:      * @return Mage_Core_Block_Abstract
 477:      */
 478:     public function unsetChildren()
 479:     {
 480:         $this->_children       = array();
 481:         $this->_sortedChildren = array();
 482:         return $this;
 483:     }
 484: 
 485:     /**
 486:      * Retrieve child block by name
 487:      *
 488:      * @param  string $name
 489:      * @return mixed
 490:      */
 491:     public function getChild($name = '')
 492:     {
 493:         if ($name === '') {
 494:             return $this->_children;
 495:         } elseif (isset($this->_children[$name])) {
 496:             return $this->_children[$name];
 497:         }
 498:         return false;
 499:     }
 500: 
 501:     /**
 502:      * Retrieve child block HTML
 503:      *
 504:      * @param   string $name
 505:      * @param   boolean $useCache
 506:      * @param   boolean $sorted
 507:      * @return  string
 508:      */
 509:     public function getChildHtml($name = '', $useCache = true, $sorted = false)
 510:     {
 511:         if ($name === '') {
 512:             if ($sorted) {
 513:                 $children = array();
 514:                 foreach ($this->getSortedChildren() as $childName) {
 515:                     $children[$childName] = $this->getLayout()->getBlock($childName);
 516:                 }
 517:             } else {
 518:                 $children = $this->getChild();
 519:             }
 520:             $out = '';
 521:             foreach ($children as $child) {
 522:                 $out .= $this->_getChildHtml($child->getBlockAlias(), $useCache);
 523:             }
 524:             return $out;
 525:         } else {
 526:             return $this->_getChildHtml($name, $useCache);
 527:         }
 528:     }
 529: 
 530:     /**
 531:      * @param string $name          Parent block name
 532:      * @param string $childName     OPTIONAL Child block name
 533:      * @param bool $useCache        OPTIONAL Use cache flag
 534:      * @param bool $sorted          OPTIONAL @see getChildHtml()
 535:      * @return string
 536:      */
 537:     public function getChildChildHtml($name, $childName = '', $useCache = true, $sorted = false)
 538:     {
 539:         if (empty($name)) {
 540:             return '';
 541:         }
 542:         $child = $this->getChild($name);
 543:         if (!$child) {
 544:             return '';
 545:         }
 546:         return $child->getChildHtml($childName, $useCache, $sorted);
 547:     }
 548: 
 549:     /**
 550:      * Obtain sorted child blocks
 551:      *
 552:      * @return array
 553:      */
 554:     public function getSortedChildBlocks()
 555:     {
 556:         $children = array();
 557:         foreach ($this->getSortedChildren() as $childName) {
 558:             $children[$childName] = $this->getLayout()->getBlock($childName);
 559:         }
 560:         return $children;
 561:     }
 562: 
 563:     /**
 564:      * Retrieve child block HTML
 565:      *
 566:      * @param   string $name
 567:      * @param   boolean $useCache
 568:      * @return  string
 569:      */
 570:     protected function _getChildHtml($name, $useCache = true)
 571:     {
 572:         if ($useCache && isset($this->_childrenHtmlCache[$name])) {
 573:             return $this->_childrenHtmlCache[$name];
 574:         }
 575: 
 576:         $child = $this->getChild($name);
 577: 
 578:         if (!$child) {
 579:             $html = '';
 580:         } else {
 581:             $this->_beforeChildToHtml($name, $child);
 582:             $html = $child->toHtml();
 583:         }
 584: 
 585:         $this->_childrenHtmlCache[$name] = $html;
 586:         return $html;
 587:     }
 588: 
 589:     /**
 590:      * Prepare child block before generate html
 591:      *
 592:      * @param   string $name
 593:      * @param   Mage_Core_Block_Abstract $child
 594:      */
 595:     protected function _beforeChildToHtml($name, $child)
 596:     {
 597:     }
 598: 
 599:     /**
 600:      * Retrieve block html
 601:      *
 602:      * @param   string $name
 603:      * @return  string
 604:      */
 605:     public function getBlockHtml($name)
 606:     {
 607:         if (!($layout = $this->getLayout()) && !($layout = $this->getAction()->getLayout())) {
 608:             return '';
 609:         }
 610:         if (!($block = $layout->getBlock($name))) {
 611:             return '';
 612:         }
 613:         return $block->toHtml();
 614:     }
 615: 
 616:     /**
 617:      * Insert child block
 618:      *
 619:      * @param   Mage_Core_Block_Abstract|string $block
 620:      * @param   string $siblingName
 621:      * @param   boolean $after
 622:      * @param   string $alias
 623:      * @return  object $this
 624:      */
 625:     public function insert($block, $siblingName = '', $after = false, $alias = '')
 626:     {
 627:         if (is_string($block)) {
 628:             $block = $this->getLayout()->getBlock($block);
 629:         }
 630:         if (!$block) {
 631:             /*
 632:              * if we don't have block - don't throw exception because
 633:              * block can simply removed using layout method remove
 634:              */
 635:             //Mage::throwException(Mage::helper('core')->__('Invalid block name to set child %s: %s', $alias, $block));
 636:             return $this;
 637:         }
 638:         if ($block->getIsAnonymous()) {
 639:             $this->setChild('', $block);
 640:             $name = $block->getNameInLayout();
 641:         } elseif ('' != $alias) {
 642:             $this->setChild($alias, $block);
 643:             $name = $block->getNameInLayout();
 644:         } else {
 645:             $name = $block->getNameInLayout();
 646:             $this->setChild($name, $block);
 647:         }
 648: 
 649:         if ($siblingName === '') {
 650:             if ($after) {
 651:                 array_push($this->_sortedChildren, $name);
 652:             } else {
 653:                 array_unshift($this->_sortedChildren, $name);
 654:             }
 655:         } else {
 656:             $key = array_search($siblingName, $this->_sortedChildren);
 657:             if (false !== $key) {
 658:                 if ($after) {
 659:                     $key++;
 660:                 }
 661:                 array_splice($this->_sortedChildren, $key, 0, $name);
 662:             } else {
 663:                 if ($after) {
 664:                     array_push($this->_sortedChildren, $name);
 665:                 } else {
 666:                     array_unshift($this->_sortedChildren, $name);
 667:                 }
 668:             }
 669: 
 670:             $this->_sortInstructions[$name] = array($siblingName, (bool)$after, false !== $key);
 671:         }
 672: 
 673:         return $this;
 674:     }
 675: 
 676:     /**
 677:      * Sort block's children
 678:      *
 679:      * @param boolean $force force re-sort all children
 680:      * @return Mage_Core_Block_Abstract
 681:      */
 682:     public function sortChildren($force = false)
 683:     {
 684:         foreach ($this->_sortInstructions as $name => $list) {
 685:             list($siblingName, $after, $exists) = $list;
 686:             if ($exists && !$force) {
 687:                 continue;
 688:             }
 689:             $this->_sortInstructions[$name][2] = true;
 690: 
 691:             $index      = array_search($name, $this->_sortedChildren);
 692:             $siblingKey = array_search($siblingName, $this->_sortedChildren);
 693: 
 694:             if ($index === false || $siblingKey === false) {
 695:                 continue;
 696:             }
 697: 
 698:             if ($after) {
 699:                 // insert after block
 700:                 if ($index == $siblingKey + 1) {
 701:                     continue;
 702:                 }
 703:                 // remove sibling from array
 704:                 array_splice($this->_sortedChildren, $index, 1, array());
 705:                 // insert sibling after
 706:                 array_splice($this->_sortedChildren, $siblingKey + 1, 0, array($name));
 707:             } else {
 708:                 // insert before block
 709:                 if ($index == $siblingKey - 1) {
 710:                     continue;
 711:                 }
 712:                 // remove sibling from array
 713:                 array_splice($this->_sortedChildren, $index, 1, array());
 714:                 // insert sibling after
 715:                 array_splice($this->_sortedChildren, $siblingKey, 0, array($name));
 716:             }
 717:         }
 718: 
 719:         return $this;
 720:     }
 721: 
 722:     /**
 723:      * Append child block
 724:      *
 725:      * @param   Mage_Core_Block_Abstract|string $block
 726:      * @param   string $alias
 727:      * @return  Mage_Core_Block_Abstract
 728:      */
 729:     public function append($block, $alias = '')
 730:     {
 731:         $this->insert($block, '', true, $alias);
 732:         return $this;
 733:     }
 734: 
 735:     /**
 736:      * Make sure specified block will be registered in the specified child groups
 737:      *
 738:      * @param string $groupName
 739:      * @param Mage_Core_Block_Abstract $child
 740:      */
 741:     public function addToChildGroup($groupName, Mage_Core_Block_Abstract $child)
 742:     {
 743:         if (!isset($this->_childGroups[$groupName])) {
 744:             $this->_childGroups[$groupName] = array();
 745:         }
 746:         if (!in_array($child->getBlockAlias(), $this->_childGroups[$groupName])) {
 747:             $this->_childGroups[$groupName][] = $child->getBlockAlias();
 748:         }
 749:     }
 750: 
 751:     /**
 752:      * Add self to the specified group of parent block
 753:      *
 754:      * @param string $groupName
 755:      * @return Mage_Core_Block_Abstract
 756:      */
 757:     public function addToParentGroup($groupName)
 758:     {
 759:         $this->getParentBlock()->addToChildGroup($groupName, $this);
 760:         return $this;
 761:     }
 762: 
 763:     /**
 764:      * Get a group of child blocks
 765:      *
 766:      * Returns an array of <alias> => <block>
 767:      * or an array of <alias> => <callback_result>
 768:      * The callback currently supports only $this methods and passes the alias as parameter
 769:      *
 770:      * @param string $groupName
 771:      * @param string $callback
 772:      * @param bool $skipEmptyResults
 773:      * @return array
 774:      */
 775:     public function getChildGroup($groupName, $callback = null, $skipEmptyResults = true)
 776:     {
 777:         $result = array();
 778:         if (!isset($this->_childGroups[$groupName])) {
 779:             return $result;
 780:         }
 781:         foreach ($this->getSortedChildBlocks() as $block) {
 782:             $alias = $block->getBlockAlias();
 783:             if (in_array($alias, $this->_childGroups[$groupName])) {
 784:                 if ($callback) {
 785:                     $row = $this->$callback($alias);
 786:                     if (!$skipEmptyResults || $row) {
 787:                         $result[$alias] = $row;
 788:                     }
 789:                 } else {
 790:                     $result[$alias] = $block;
 791:                 }
 792: 
 793:             }
 794:         }
 795:         return $result;
 796:     }
 797: 
 798:     /**
 799:      * Get a value from child block by specified key
 800:      *
 801:      * @param string $alias
 802:      * @param string $key
 803:      * @return mixed
 804:      */
 805:     public function getChildData($alias, $key = '')
 806:     {
 807:         $child = $this->getChild($alias);
 808:         if ($child) {
 809:             return $child->getData($key);
 810:         }
 811:     }
 812: 
 813:     /**
 814:      * Before rendering html, but after trying to load cache
 815:      *
 816:      * @return Mage_Core_Block_Abstract
 817:      */
 818:     protected function _beforeToHtml()
 819:     {
 820:         return $this;
 821:     }
 822: 
 823:     /**
 824:      * Specify block output frame tags
 825:      *
 826:      * @param $openTag
 827:      * @param $closeTag
 828:      * @return Mage_Core_Block_Abstract
 829:      */
 830:     public function setFrameTags($openTag, $closeTag = null)
 831:     {
 832:         $this->_frameOpenTag = $openTag;
 833:         if ($closeTag) {
 834:             $this->_frameCloseTag = $closeTag;
 835:         } else {
 836:             $this->_frameCloseTag = '/' . $openTag;
 837:         }
 838:         return $this;
 839:     }
 840: 
 841:     /**
 842:      * Produce and return block's html output
 843:      *
 844:      * It is a final method, but you can override _toHtml() method in descendants if needed.
 845:      *
 846:      * @return string
 847:      */
 848:     final public function toHtml()
 849:     {
 850:         Mage::dispatchEvent('core_block_abstract_to_html_before', array('block' => $this));
 851:         if (Mage::getStoreConfig('advanced/modules_disable_output/' . $this->getModuleName())) {
 852:             return '';
 853:         }
 854:         $html = $this->_loadCache();
 855:         if ($html === false) {
 856:             $translate = Mage::getSingleton('core/translate');
 857:             /** @var $translate Mage_Core_Model_Translate */
 858:             if ($this->hasData('translate_inline')) {
 859:                 $translate->setTranslateInline($this->getData('translate_inline'));
 860:             }
 861: 
 862:             $this->_beforeToHtml();
 863:             $html = $this->_toHtml();
 864:             $this->_saveCache($html);
 865: 
 866:             if ($this->hasData('translate_inline')) {
 867:                 $translate->setTranslateInline(true);
 868:             }
 869:         }
 870:         $html = $this->_afterToHtml($html);
 871: 
 872:         /**
 873:          * Check framing options
 874:          */
 875:         if ($this->_frameOpenTag) {
 876:             $html = '<'.$this->_frameOpenTag.'>'.$html.'<'.$this->_frameCloseTag.'>';
 877:         }
 878: 
 879:         /**
 880:          * Use single transport object instance for all blocks
 881:          */
 882:         if (self::$_transportObject === null) {
 883:             self::$_transportObject = new Varien_Object;
 884:         }
 885:         self::$_transportObject->setHtml($html);
 886:         Mage::dispatchEvent('core_block_abstract_to_html_after',
 887:                 array('block' => $this, 'transport' => self::$_transportObject));
 888:         $html = self::$_transportObject->getHtml();
 889: 
 890:         return $html;
 891:     }
 892: 
 893:     /**
 894:      * Processing block html after rendering
 895:      *
 896:      * @param   string $html
 897:      * @return  string
 898:      */
 899:     protected function _afterToHtml($html)
 900:     {
 901:         return $html;
 902:     }
 903: 
 904:     /**
 905:      * Override this method in descendants to produce html
 906:      *
 907:      * @return string
 908:      */
 909:     protected function _toHtml()
 910:     {
 911:         return '';
 912:     }
 913: 
 914:     /**
 915:      * Returns url model class name
 916:      *
 917:      * @return string
 918:      */
 919:     protected function _getUrlModelClass()
 920:     {
 921:         return 'core/url';
 922:     }
 923: 
 924:     /**
 925:      * Create and return url object
 926:      *
 927:      * @return Mage_Core_Model_Url
 928:      */
 929:     protected function _getUrlModel()
 930:     {
 931:         return Mage::getModel($this->_getUrlModelClass());
 932:     }
 933: 
 934:     /**
 935:      * Generate url by route and parameters
 936:      *
 937:      * @param   string $route
 938:      * @param   array $params
 939:      * @return  string
 940:      */
 941:     public function getUrl($route = '', $params = array())
 942:     {
 943:         return $this->_getUrlModel()->getUrl($route, $params);
 944:     }
 945: 
 946:     /**
 947:      * Generate base64-encoded url by route and parameters
 948:      *
 949:      * @param   string $route
 950:      * @param   array $params
 951:      * @return  string
 952:      */
 953:     public function getUrlBase64($route = '', $params = array())
 954:     {
 955:         return Mage::helper('core')->urlEncode($this->getUrl($route, $params));
 956:     }
 957: 
 958:     /**
 959:      * Generate url-encoded url by route and parameters
 960:      *
 961:      * @param   string $route
 962:      * @param   array $params
 963:      * @return  string
 964:      */
 965:     public function getUrlEncoded($route = '', $params = array())
 966:     {
 967:         return Mage::helper('core')->urlEncode($this->getUrl($route, $params));
 968:     }
 969: 
 970:     /**
 971:      * Retrieve url of skins file
 972:      *
 973:      * @param   string $file path to file in skin
 974:      * @param   array $params
 975:      * @return  string
 976:      */
 977:     public function getSkinUrl($file = null, array $params = array())
 978:     {
 979:         return Mage::getDesign()->getSkinUrl($file, $params);
 980:     }
 981: 
 982:     /**
 983:      * Retrieve messages block
 984:      *
 985:      * @return Mage_Core_Block_Messages
 986:      */
 987:     public function getMessagesBlock()
 988:     {
 989:         if (is_null($this->_messagesBlock)) {
 990:             return $this->getLayout()->getMessagesBlock();
 991:         }
 992:         return $this->_messagesBlock;
 993:     }
 994: 
 995:     /**
 996:      * Set messages block
 997:      *
 998:      * @param   Mage_Core_Block_Messages $block
 999:      * @return  Mage_Core_Block_Abstract
1000:      */
1001:     public function setMessagesBlock(Mage_Core_Block_Messages $block)
1002:     {
1003:         $this->_messagesBlock = $block;
1004:         return $this;
1005:     }
1006: 
1007:     /**
1008:      * Return block helper
1009:      *
1010:      * @param string $type
1011:      * @return Mage_Core_Block_Abstract
1012:      */
1013:     public function getHelper($type)
1014:     {
1015:         return $this->getLayout()->getBlockSingleton($type);
1016:     }
1017: 
1018:     /**
1019:      * Returns helper object
1020:      *
1021:      * @param string $name
1022:      * @return Mage_Core_Block_Abstract
1023:      */
1024:     public function helper($name)
1025:     {
1026:         if ($this->getLayout()) {
1027:             return $this->getLayout()->helper($name);
1028:         }
1029:         return Mage::helper($name);
1030:     }
1031: 
1032:     /**
1033:      * Retrieve formatting date
1034:      *
1035:      * @param   string $date
1036:      * @param   string $format
1037:      * @param   bool $showTime
1038:      * @return  string
1039:      */
1040:     public function formatDate($date = null, $format =  Mage_Core_Model_Locale::FORMAT_TYPE_SHORT, $showTime = false)
1041:     {
1042:         return $this->helper('core')->formatDate($date, $format, $showTime);
1043:     }
1044: 
1045:     /**
1046:      * Retrieve formatting time
1047:      *
1048:      * @param   string $time
1049:      * @param   string $format
1050:      * @param   bool $showDate
1051:      * @return  string
1052:      */
1053:     public function formatTime($time = null, $format =  Mage_Core_Model_Locale::FORMAT_TYPE_SHORT, $showDate = false)
1054:     {
1055:         return $this->helper('core')->formatTime($time, $format, $showDate);
1056:     }
1057: 
1058:     /**
1059:      * Retrieve module name of block
1060:      *
1061:      * @return string
1062:      */
1063:     public function getModuleName()
1064:     {
1065:         $module = $this->getData('module_name');
1066:         if (is_null($module)) {
1067:             $class = get_class($this);
1068:             $module = substr($class, 0, strpos($class, '_Block'));
1069:             $this->setData('module_name', $module);
1070:         }
1071:         return $module;
1072:     }
1073: 
1074:     /**
1075:      * Translate block sentence
1076:      *
1077:      * @return string
1078:      */
1079:     public function __()
1080:     {
1081:         $args = func_get_args();
1082:         $expr = new Mage_Core_Model_Translate_Expr(array_shift($args), $this->getModuleName());
1083:         array_unshift($args, $expr);
1084:         return Mage::app()->getTranslator()->translate($args);
1085:     }
1086: 
1087:     /**
1088:      * @deprecated after 1.4.0.0-rc1
1089:      * @see self::escapeHtml()
1090:      */
1091:     public function htmlEscape($data, $allowedTags = null)
1092:     {
1093:         return $this->escapeHtml($data, $allowedTags);
1094:     }
1095: 
1096:     /**
1097:      * Escape html entities
1098:      *
1099:      * @param   mixed $data
1100:      * @param   array $allowedTags
1101:      * @return  string
1102:      */
1103:     public function escapeHtml($data, $allowedTags = null)
1104:     {
1105:         return $this->helper('core')->escapeHtml($data, $allowedTags);
1106:     }
1107: 
1108:     /**
1109:      * Wrapper for standard strip_tags() function with extra functionality for html entities
1110:      *
1111:      * @param string $data
1112:      * @param string $allowableTags
1113:      * @param bool $allowHtmlEntities
1114:      * @return string
1115:      */
1116:     public function stripTags($data, $allowableTags = null, $allowHtmlEntities = false)
1117:     {
1118:         return $this->helper('core')->stripTags($data, $allowableTags, $allowHtmlEntities);
1119:     }
1120: 
1121:     /**
1122:      * @deprecated after 1.4.0.0-rc1
1123:      * @see self::escapeUrl()
1124:      */
1125:     public function urlEscape($data)
1126:     {
1127:         return $this->escapeUrl($data);
1128:     }
1129: 
1130:     /**
1131:      * Escape html entities in url
1132:      *
1133:      * @param string $data
1134:      * @return string
1135:      */
1136:     public function escapeUrl($data)
1137:     {
1138:         return $this->helper('core')->escapeUrl($data);
1139:     }
1140: 
1141:     /**
1142:      * Escape quotes in java scripts
1143:      *
1144:      * @param mixed $data
1145:      * @param string $quote
1146:      * @return mixed
1147:      */
1148:     public function jsQuoteEscape($data, $quote = '\'')
1149:     {
1150:         return $this->helper('core')->jsQuoteEscape($data, $quote);
1151:     }
1152: 
1153:     /**
1154:      * Alias for getName method.
1155:      *
1156:      * @return string
1157:      */
1158:     public function getNameInLayout()
1159:     {
1160:         return $this->_nameInLayout;
1161:     }
1162: 
1163:     /**
1164:      * Get chilren blocks count
1165:      * @return int
1166:      */
1167:     public function countChildren()
1168:     {
1169:         return count($this->_children);
1170:     }
1171: 
1172:     /**
1173:      * Prepare url for save to cache
1174:      *
1175:      * @return Mage_Core_Block_Abstract
1176:      */
1177:     protected function _beforeCacheUrl()
1178:     {
1179:         if (Mage::app()->useCache(self::CACHE_GROUP)) {
1180:             Mage::app()->setUseSessionVar(true);
1181:         }
1182:         return $this;
1183:     }
1184: 
1185:     /**
1186:      * Replace URLs from cache
1187:      *
1188:      * @param string $html
1189:      * @return string
1190:      */
1191:     protected function _afterCacheUrl($html)
1192:     {
1193:         if (Mage::app()->useCache(self::CACHE_GROUP)) {
1194:             Mage::app()->setUseSessionVar(false);
1195:             Varien_Profiler::start('CACHE_URL');
1196:             $html = Mage::getSingleton($this->_getUrlModelClass())->sessionUrlVar($html);
1197:             Varien_Profiler::stop('CACHE_URL');
1198:         }
1199:         return $html;
1200:     }
1201: 
1202:     /**
1203:      * Get cache key informative items
1204:      * Provide string array key to share specific info item with FPC placeholder
1205:      *
1206:      * @return array
1207:      */
1208:     public function getCacheKeyInfo()
1209:     {
1210:         return array(
1211:             $this->getNameInLayout()
1212:         );
1213:     }
1214: 
1215:     /**
1216:      * Get Key for caching block content
1217:      *
1218:      * @return string
1219:      */
1220:     public function getCacheKey()
1221:     {
1222:         if ($this->hasData('cache_key')) {
1223:             return $this->getData('cache_key');
1224:         }
1225:         /**
1226:          * don't prevent recalculation by saving generated cache key
1227:          * because of ability to render single block instance with different data
1228:          */
1229:         $key = $this->getCacheKeyInfo();
1230:         //ksort($key);  // ignore order
1231:         $key = array_values($key);  // ignore array keys
1232:         $key = implode('|', $key);
1233:         $key = sha1($key);
1234:         return $key;
1235:     }
1236: 
1237:     /**
1238:      * Get tags array for saving cache
1239:      *
1240:      * @return array
1241:      */
1242:     public function getCacheTags()
1243:     {
1244:         if (!$this->hasData('cache_tags')) {
1245:             $tags = array();
1246:         } else {
1247:             $tags = $this->getData('cache_tags');
1248:         }
1249:         $tags[] = self::CACHE_GROUP;
1250:         return $tags;
1251:     }
1252: 
1253:     /**
1254:      * Get block cache life time
1255:      *
1256:      * @return int
1257:      */
1258:     public function getCacheLifetime()
1259:     {
1260:         if (!$this->hasData('cache_lifetime')) {
1261:             return null;
1262:         }
1263:         return $this->getData('cache_lifetime');
1264:     }
1265: 
1266:     /**
1267:      * Load block html from cache storage
1268:      *
1269:      * @return string | false
1270:      */
1271:     protected function _loadCache()
1272:     {
1273:         if (is_null($this->getCacheLifetime()) || !Mage::app()->useCache(self::CACHE_GROUP)) {
1274:             return false;
1275:         }
1276:         $cacheKey = $this->getCacheKey();
1277:         /** @var $session Mage_Core_Model_Session */
1278:         $session = Mage::getSingleton('core/session');
1279:         $cacheData = Mage::app()->loadCache($cacheKey);
1280:         if ($cacheData) {
1281:             $cacheData = str_replace(
1282:                 $this->_getSidPlaceholder($cacheKey),
1283:                 $session->getSessionIdQueryParam() . '=' . $session->getEncryptedSessionId(),
1284:                 $cacheData
1285:             );
1286:         }
1287:         return $cacheData;
1288:     }
1289: 
1290:     /**
1291:      * Save block content to cache storage
1292:      *
1293:      * @param string $data
1294:      * @return Mage_Core_Block_Abstract
1295:      */
1296:     protected function _saveCache($data)
1297:     {
1298:         if (is_null($this->getCacheLifetime()) || !Mage::app()->useCache(self::CACHE_GROUP)) {
1299:             return false;
1300:         }
1301:         $cacheKey = $this->getCacheKey();
1302:         /** @var $session Mage_Core_Model_Session */
1303:         $session = Mage::getSingleton('core/session');
1304:         $data = str_replace(
1305:             $session->getSessionIdQueryParam() . '=' . $session->getEncryptedSessionId(),
1306:             $this->_getSidPlaceholder($cacheKey),
1307:             $data
1308:         );
1309: 
1310:         Mage::app()->saveCache($data, $cacheKey, $this->getCacheTags(), $this->getCacheLifetime());
1311:         return $this;
1312:     }
1313: 
1314:     /**
1315:      * Get SID placeholder for cache
1316:      *
1317:      * @param null|string $cacheKey
1318:      * @return string
1319:      */
1320:     protected function _getSidPlaceholder($cacheKey = null)
1321:     {
1322:         if (is_null($cacheKey)) {
1323:             $cacheKey = $this->getCacheKey();
1324:         }
1325: 
1326:         return '<!--SID=' . $cacheKey . '-->';
1327:     }
1328: }
1329: