inc/classes/main/template/menu/class_MenuTemplateEngine.php

   1 <?php
   2 /**
   3  * A Menu template engine class
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 Core Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.ship-simu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class MenuTemplateEngine extends BaseTemplateEngine implements CompileableTemplate {
  25         /**
  26          * Main nodes in the XML tree ('menu' is ignored)
  27          */
  28         private $mainNodes = array(
  29                 'block-list',
  30         );
  31
  32         /**
  33          * Sub nodes in the XML tree
  34          */
  35         private $subNodes = array(
  36                 'entry-list',
  37                 'entry',
  38                 'entry-id',
  39                 'entries-content',
  40                 'block-header',
  41                 'block-footer',
  42                 'footer-id',
  43                 'footer-class',
  44                 'footer-text',
  45                 'block',
  46                 'title',
  47                 'title-id',
  48                 'title-class',
  49                 'title-text',
  50                 'design',
  51                 'text',
  52                 'advert',
  53                 'anchor',
  54                 'anchor-id',
  55                 'anchor-text',
  56                 'anchor-title',
  57                 'anchor-href',
  58         );
  59
  60         /**
  61          * Menu instance
  62          */
  63         private $menuInstance = null;
  64
  65         /**
  66          * Current main node
  67          */
  68         private $curr = array();
  69
  70         /**
  71          * Content from dependency
  72          */
  73         private $dependencyContent = array();
  74
  75         /**
  76          * Protected constructor
  77          *
  78          * @return      void
  79          */
  80         protected function __construct () {
  81                 // Call parent constructor
  82                 parent::__construct(__CLASS__);
  83         }
  84
  85         /**
  86          * Creates an instance of the class TemplateEngine and prepares it for usage
  87          *
  88          * @param       $appInstance    A manageable application
  89          * @param       $menuInstance   A RenderableMenu instance
  90          * @return      $tplInstance    An instance of TemplateEngine
  91          * @throws      BasePathIsEmptyException                If the provided $templateBasePath is empty
  92          * @throws      InvalidBasePathStringException  If $templateBasePath is no string
  93          * @throws      BasePathIsNoDirectoryException  If $templateBasePath is no
  94          *                                                                                      directory or not found
  95          * @throws      BasePathReadProtectedException  If $templateBasePath is
  96          *                                                                                      read-protected
  97          */
  98         public final static function createMenuTemplateEngine (ManageableApplication $appInstance, RenderableMenu $menuInstance) {
  99                 // Get a new instance
 100                 $tplInstance = new MenuTemplateEngine();
 101
 102                 // Get language and file I/O instances from application
 103                 $langInstance = $appInstance->getLanguageInstance();
 104                 $ioInstance = $appInstance->getFileIoInstance();
 105
 106                 // Determine base path
 107                 $templateBasePath = $tplInstance->getConfigInstance()->getConfigEntry('application_base_path') . $appInstance->getRequestInstance()->getRequestElement('app') . '/';
 108
 109                 // Is the base path valid?
 110                 if (empty($templateBasePath)) {
 111                         // Base path is empty
 112                         throw new BasePathIsEmptyException($tplInstance, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 113                 } elseif (!is_string($templateBasePath)) {
 114                         // Is not a string
 115                         throw new InvalidBasePathStringException(array($tplInstance, $templateBasePath), self::EXCEPTION_INVALID_STRING);
 116                 } elseif (!is_dir($templateBasePath)) {
 117                         // Is not a path
 118                         throw new BasePathIsNoDirectoryException(array($tplInstance, $templateBasePath), self::EXCEPTION_INVALID_PATH_NAME);
 119                 } elseif (!is_readable($templateBasePath)) {
 120                         // Is not readable
 121                         throw new BasePathReadProtectedException(array($tplInstance, $templateBasePath), self::EXCEPTION_READ_PROTECED_PATH);
 122                 }
 123
 124                 // Get configuration instance
 125                 $configInstance = FrameworkConfiguration::getInstance();
 126
 127                 // Set the base path
 128                 $tplInstance->setTemplateBasePath($templateBasePath);
 129
 130                 // Set the language and IO instances
 131                 $tplInstance->setLanguageInstance($langInstance);
 132                 $tplInstance->setFileIoInstance($ioInstance);
 133
 134                 // Set template extensions
 135                 $tplInstance->setRawTemplateExtension($configInstance->getConfigEntry('raw_template_extension'));
 136                 $tplInstance->setCodeTemplateExtension($configInstance->getConfigEntry('menu_template_extension'));
 137
 138                 // Absolute output path for compiled templates
 139                 $tplInstance->setCompileOutputPath($configInstance->getConfigEntry('base_path') . $configInstance->getConfigEntry('compile_output_path'));
 140
 141                 // Set the menu instance
 142                 $tplInstance->setMenuInstance($menuInstance);
 143
 144                 // Init a variable stacker
 145                 $stackerInstance = ObjectFactory::createObjectByConfiguredName('menu_stacker_class');
 146
 147                 // Set it
 148                 $tplInstance->setStackerInstance($stackerInstance);
 149
 150                 // Return the prepared instance
 151                 return $tplInstance;
 152         }
 153
 154         /**
 155          * Load a specified menu template into the engine
 156          *
 157          * @param       $template       The menu template we shall load which is
 158          *                                              located in 'menu' by default
 159          * @return      void
 160          */
 161         public function loadMenuTemplate ($template) {
 162                 // Set template type
 163                 $this->setTemplateType($this->getConfigInstance()->getConfigEntry('menu_template_type'));
 164
 165                 // Load the special template
 166                 $this->loadTemplate($template);
 167         }
 168
 169         /**
 170          * Getter for current main node
 171          *
 172          * @return      $currMainNode   Current main node
 173          */
 174         public final function getCurrMainNode () {
 175                 return $this->curr['main_node'];
 176         }
 177
 178         /**
 179          * Setter for current main node
 180          *
 181          * @param       $element                Element name to set as current main node
 182          * @return      $currMainNode   Current main node
 183          */
 184         private final function setCurrMainNode ($element) {
 185                 $this->curr['main_node'] = (string) $element;
 186         }
 187
 188         /**
 189          * Getter for main node array
 190          *
 191          * @return      $mainNodes      Array with valid main node names
 192          */
 193         public final function getMainNodes () {
 194                 return $this->mainNodes;
 195         }
 196
 197         /**
 198          * Getter for sub node array
 199          *
 200          * @return      $subNodes       Array with valid sub node names
 201          */
 202         public final function getSubNodes () {
 203                 return $this->subNodes;
 204         }
 205
 206         /**
 207          * Handles the start element of an XML resource
 208          *
 209          * @param       $resource               XML parser resource (currently ignored)
 210          * @param       $element                The element we shall handle
 211          * @param       $attributes             All attributes
 212          * @return      void
 213          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
 214          */
 215         public function startElement ($resource, $element, array $attributes) {
 216                 // Initial method name which will never be called...
 217                 $methodName = 'initMenu';
 218
 219                 // Make the element name lower-case
 220                 $element = strtolower($element);
 221
 222                 // Is the element a main node?
 223                 //* DEBUG: */ echo "START: &gt;".$element."&lt;<br />\n";
 224                 if (in_array($element, $this->getMainNodes())) {
 225                         // Okay, main node found!
 226                         $methodName = 'start' . $this->convertToClassName($element);
 227
 228                         // Set it
 229                         $this->setCurrMainNode($element);
 230                 } elseif (in_array($element, $this->getSubNodes())) {
 231                         // Sub node found
 232                         $methodName = 'start' . $this->convertToClassName($element);
 233                 } elseif ($element != 'menu') {
 234                         // Invalid node name found
 235                         throw new InvalidXmlNodeException(array($this, $element, $attributes), XmlParser::EXCEPTION_XML_NODE_UNKNOWN);
 236                 }
 237
 238                 // Call method
 239                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 240                 call_user_func_array(array($this, $methodName), $attributes);
 241         }
 242
 243         /**
 244          * Ends the main or sub node by sending out the gathered data
 245          *
 246          * @param       $resource       An XML resource pointer (currently ignored)
 247          * @param       $nodeName       Name of the node we want to finish
 248          * @return      void
 249          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
 250          */
 251         public function endElement ($resource, $nodeName) {
 252                 // Make all lower-case
 253                 $nodeName = strtolower($nodeName);
 254
 255                 // Does this match with current main node?
 256                 //* DEBUG: */ echo "END: &gt;".$nodeName."&lt;<br />\n";
 257                 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
 258                         // Did not match!
 259                         throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), XmlParser::EXCEPTION_XML_NODE_MISMATCH);
 260                 } // END - if
 261
 262                 // Construct method name
 263                 $methodName = 'finish' . $this->convertToClassName($nodeName);
 264
 265                 // Call the corresponding method
 266                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 267                 call_user_func_array(array($this, $methodName), array());
 268         }
 269
 270         /**
 271          * Currently not used
 272          *
 273          * @param       $resource               XML parser resource (currently ignored)
 274          * @param       $characters             Characters to handle
 275          * @return      void
 276          * @todo        Find something useful with this!
 277          */
 278         public function characterHandler ($resource, $characters) {
 279                 // Trim all spaces away
 280                 $characters = trim($characters);
 281
 282                 // Is this string empty?
 283                 if (empty($characters)) {
 284                         // Then skip it silently
 285                         return false;
 286                 } // END - if
 287
 288                 // Assign the found characters to variable and use the last entry from
 289                 // stack as the name
 290                 parent::assignVariable($this->getStackerInstance()->getNamed('current_node'), $characters);
 291         }
 292
 293         /**
 294          * Handles the template dependency for given node
 295          *
 296          * @param       $node                                   The node we should load a dependency template
 297          * @param       $templateDependency             A template to load to satisfy dependencies
 298          * @return      void
 299          */
 300         private function handleTemplateDependency ($node, $templateDependency) {
 301                 // Is the template dependency set?
 302                 if ((!empty($templateDependency)) && (!isset($this->dependencyContent[$node]))) {
 303                         // Get a temporay menu template instance
 304                         $templateInstance = ObjectFactory::createObjectByConfiguredName('menu_template_class', array($this->getApplicationInstance(), $this->getMenuInstance()));
 305
 306                         // Then load it
 307                         $templateInstance->loadMenuTemplate($templateDependency);
 308
 309                         // Get an XmlParser instance
 310                         $templateInstance->renderXmlContent();
 311
 312                         // Parse the template's content contents
 313                         $this->dependencyContent[$node] = $templateInstance->getRawTemplateData();
 314                 } // END - if
 315         }
 316
 317         /**
 318          * Intializes the menu
 319          *
 320          * @param       $templateDependency             A template to load to satisfy dependencies
 321          * @return      void
 322          * @todo        Add cache creation here
 323          */
 324         private function initMenu ($templateDependency = '') {
 325                 // Get web template engine
 326                 $this->setTemplateInstance(ObjectFactory::createObjectByConfiguredName('web_template_class', array($this->getApplicationInstance())));
 327
 328                 // Handle the dependency template
 329                 $this->handleTemplateDependency('menu', $templateDependency);
 330
 331                 // Code cleaned up...
 332                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 333         }
 334
 335         /**
 336          * Finishes the menu
 337          *
 338          * @return      void
 339          */
 340         private function finishMenu () {
 341                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 342         }
 343
 344         /**
 345          * Starts the menu entries by loading a (maybe) provided template dependency
 346          *
 347          * @param       $templateDependency     A template to load to satisfy dependencies
 348          * @return      void
 349          */
 350         private function startEntryList ($templateDependency = '') {
 351                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 352         }
 353
 354         /**
 355          * Finishes the menu entries
 356          *
 357          * @return      void
 358          */
 359         private function finishEntryList () {
 360                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 361         }
 362
 363         /**
 364          * Starts the menu block header
 365          *
 366          * @return      void
 367          */
 368         private function startBlockHeader () {
 369                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 370         }
 371
 372         /**
 373          * Finishes the menu block header
 374          *
 375          * @return      void
 376          */
 377         private function finishBlockHeader () {
 378                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 379         }
 380
 381         /**
 382          * Starts the menu block footer
 383          *
 384          * @return      void
 385          */
 386         private function startBlockFooter () {
 387                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 388         }
 389
 390         /**
 391          * Finishes the menu block footer
 392          *
 393          * @return      void
 394          */
 395         private function finishBlockFooter () {
 396                 $this->partialStub('Cleaned because we do not want templates with partly HTML code.');
 397         }
 398
 399         /**
 400          * Starts the menu property 'block-list'
 401          *
 402          * @return      void
 403          */
 404         private function startBlockList () {
 405                 // Push the node name on the stacker
 406                 $this->getStackerInstance()->pushNamed('current_node', 'block-list');
 407         }
 408
 409         /**
 410          * Starts the menu property 'block'
 411          *
 412          * @return      void
 413          */
 414         private function startBlock () {
 415                 // Push the node name on the stacker
 416                 $this->getStackerInstance()->pushNamed('current_node', 'block');
 417         }
 418
 419         /**
 420          * Starts the menu property 'title'
 421          *
 422          * @return      void
 423          */
 424         private function startTitle () {
 425                 // Push the node name on the stacker
 426                 $this->getStackerInstance()->pushNamed('current_node', 'title');
 427         }
 428
 429         /**
 430          * Starts the menu property 'title-id'
 431          *
 432          * @return      void
 433          */
 434         private function startTitleId () {
 435                 // Push the node name on the stacker
 436                 $this->getStackerInstance()->pushNamed('current_node', 'title-id');
 437         }
 438
 439         /**
 440          * Starts the menu property 'title-class'
 441          *
 442          * @return      void
 443          */
 444         private function startTitleClass () {
 445                 // Push the node name on the stacker
 446                 $this->getStackerInstance()->pushNamed('current_node', 'title-class');
 447         }
 448
 449         /**
 450          * Starts the menu property 'title-text'
 451          *
 452          * @return      void
 453          */
 454         private function startTitleText () {
 455                 // Push the node name on the stacker
 456                 $this->getStackerInstance()->pushNamed('current_node', 'title-text');
 457         }
 458
 459         /**
 460          * Starts the menu property 'entry'
 461          *
 462          * @return      void
 463          */
 464         private function startEntry () {
 465                 // Push the node name on the stacker
 466                 $this->getStackerInstance()->pushNamed('current_node', 'entry');
 467         }
 468
 469         /**
 470          * Starts the menu property 'entry-id'
 471          *
 472          * @return      void
 473          */
 474         private function startEntryId () {
 475                 // Push the node name on the stacker
 476                 $this->getStackerInstance()->pushNamed('current_node', 'entry-id');
 477         }
 478
 479         /**
 480          * Starts the menu property 'anchor'
 481          *
 482          * @return      void
 483          */
 484         private function startAnchor () {
 485                 // Push the node name on the stacker
 486                 $this->getStackerInstance()->pushNamed('current_node', 'anchor');
 487         }
 488
 489         /**
 490          * Starts the menu property 'anchor-id'
 491          *
 492          * @return      void
 493          */
 494         private function startAnchorId () {
 495                 // Push the node name on the stacker
 496                 $this->getStackerInstance()->pushNamed('current_node', 'anchor-id');
 497         }
 498
 499         /**
 500          * Starts the menu property 'anchor-text'
 501          *
 502          * @return      void
 503          */
 504         private function startAnchorText () {
 505                 // Push the node name on the stacker
 506                 $this->getStackerInstance()->pushNamed('current_node', 'anchor-text');
 507         }
 508
 509         /**
 510          * Starts the menu property 'anchor-title'
 511          *
 512          * @return      void
 513          */
 514         private function startAnchorTitle () {
 515                 // Push the node name on the stacker
 516                 $this->getStackerInstance()->pushNamed('current_node', 'anchor-title');
 517         }
 518
 519         /**
 520          * Starts the menu property 'anchor-href'
 521          *
 522          * @return      void
 523          */
 524         private function startAnchorHref () {
 525                 // Push the node name on the stacker
 526                 $this->getStackerInstance()->pushNamed('current_node', 'anchor-href');
 527         }
 528
 529         /**
 530          * Starts the menu property 'footer-id'
 531          *
 532          * @return      void
 533          */
 534         private function startFooterId () {
 535                 // Push the node name on the stacker
 536                 $this->getStackerInstance()->pushNamed('current_node', 'footer-id');
 537         }
 538
 539         /**
 540          * Starts the menu property 'footer-class'
 541          *
 542          * @return      void
 543          */
 544         private function startFooterClass () {
 545                 // Push the node name on the stacker
 546                 $this->getStackerInstance()->pushNamed('current_node', 'footer-class');
 547         }
 548
 549         /**
 550          * Starts the menu property 'footer-text'
 551          *
 552          * @return      void
 553          */
 554         private function startFooterText () {
 555                 // Push the node name on the stacker
 556                 $this->getStackerInstance()->pushNamed('current_node', 'footer-text');
 557         }
 558
 559         /**
 560          * Finishes the title node by added another template to the menu
 561          *
 562          * @return      void
 563          */
 564         private function finishTitle () {
 565                 // Pop the last entry
 566                 $this->getStackerInstance()->popNamed('current_node');
 567         }
 568
 569         /**
 570          * Finishes the title-id node by
 571          *
 572          * @return      void
 573          */
 574         private function finishTitleId () {
 575                 // Pop the last entry
 576                 $this->getStackerInstance()->popNamed('current_node');
 577         }
 578
 579         /**
 580          * Finishes the title-class node
 581          *
 582          * @return      void
 583          */
 584         private function finishTitleClass () {
 585                 // Pop the last entry
 586                 $this->getStackerInstance()->popNamed('current_node');
 587         }
 588
 589         /**
 590          * Finishes the title-class node
 591          *
 592          * @return      void
 593          */
 594         private function finishTitleText () {
 595                 // Pop the last entry
 596                 $this->getStackerInstance()->popNamed('current_node');
 597         }
 598
 599         /**
 600          * Finishes the footer-text node
 601          *
 602          * @return      void
 603          */
 604         private function finishFooterText () {
 605                 // Pop the last entry
 606                 $this->getStackerInstance()->popNamed('current_node');
 607         }
 608
 609         /**
 610          * Finishes the footer-class node
 611          *
 612          * @return      void
 613          */
 614         private function finishFooterClass () {
 615                 // Pop the last entry
 616                 $this->getStackerInstance()->popNamed('current_node');
 617         }
 618
 619         /**
 620          * Finishes the footer-id node
 621          *
 622          * @return      void
 623          */
 624         private function finishFooterId () {
 625                 // Pop the last entry
 626                 $this->getStackerInstance()->popNamed('current_node');
 627         }
 628
 629         /**
 630          * Finishes the anchor-href node
 631          *
 632          * @return      void
 633          */
 634         private function finishAnchorHref () {
 635                 // Pop the last entry
 636                 $this->getStackerInstance()->popNamed('current_node');
 637         }
 638
 639         /**
 640          * Finishes the anchor-title node
 641          *
 642          * @return      void
 643          */
 644         private function finishAnchorTitle () {
 645                 // Pop the last entry
 646                 $this->getStackerInstance()->popNamed('current_node');
 647         }
 648
 649         /**
 650          * Finishes the anchor-text node
 651          *
 652          * @return      void
 653          */
 654         private function finishAnchorText () {
 655                 // Pop the last entry
 656                 $this->getStackerInstance()->popNamed('current_node');
 657         }
 658
 659         /**
 660          * Finishes the anchor-id node
 661          *
 662          * @return      void
 663          */
 664         private function finishAnchorId () {
 665                 // Pop the last entry
 666                 $this->getStackerInstance()->popNamed('current_node');
 667         }
 668
 669         /**
 670          * Finishes the anchor node
 671          *
 672          * @return      void
 673          */
 674         private function finishAnchor () {
 675                 // Pop the last entry
 676                 $this->getStackerInstance()->popNamed('current_node');
 677         }
 678
 679         /**
 680          * Finishes the entry-id node
 681          *
 682          * @return      void
 683          */
 684         private function finishEntryId () {
 685                 // Pop the last entry
 686                 $this->getStackerInstance()->popNamed('current_node');
 687         }
 688
 689         /**
 690          * Finishes the entry node
 691          *
 692          * @return      void
 693          */
 694         private function finishEntry () {
 695                 // Pop the last entry
 696                 $this->getStackerInstance()->popNamed('current_node');
 697         }
 698
 699         /**
 700          * Finishes the block node
 701          *
 702          * @return      void
 703          */
 704         private function finishBlock () {
 705                 // Pop the last entry
 706                 $this->getStackerInstance()->popNamed('current_node');
 707         }
 708
 709         /**
 710          * Finishes the block-list node
 711          *
 712          * @return      void
 713          */
 714         private function finishBlockList () {
 715                 // Pop the last entry
 716                 $this->getStackerInstance()->popNamed('current_node');
 717         }
 718
 719         /**
 720          * Starts the menu text
 721          *
 722          * @return      void
 723          */
 724         private function startText () {
 725                 // Do we have a template instance?
 726                 if (is_null($this->getTemplateInstance())) {
 727                         // Init template instance for underlaying web templates
 728                         $templateInstance = ObjectFactory::createObjectByConfiguredName('web_template_class');
 729
 730                         // Set it in this template engine
 731                         $this->setTemplateInstance($templateInstance);
 732                 } // END - if
 733
 734                 // Load the text template for this page
 735                 $this->getTemplateInstance()->loadCodeTemplate('menu_text_start');
 736
 737                 // Set the variable group to page
 738                 $this->setVariableGroup('menu');
 739
 740                 // Set its content in this template instance
 741                 $this->assignVariable('text', $this->getTemplateInstance()->getRawTemplateData());
 742         }
 743
 744         /**
 745          * Finishes the menu text
 746          *
 747          * @return      void
 748          */
 749         private function finishText () {
 750                 // Load the text template for this page
 751                 $this->getTemplateInstance()->loadCodeTemplate('menu_text_end');
 752
 753                 // Set the variable group to page
 754                 $this->setVariableGroup('menu');
 755
 756                 // Set its content in this template instance
 757                 $this->assignVariable('text_end', $this->getTemplateInstance()->getRawTemplateData());
 758         }
 759
 760         /**
 761          * Getter for menu cache file (FQFN)
 762          *
 763          * @return      $fqfn   Full-qualified file name of the menu cache
 764          */
 765         public function getMenuCacheFqfn () {
 766                 // Get the FQFN ready
 767                 $fqfn = sprintf("%s%s%s/%s.%s",
 768                         $this->getConfigInstance()->getConfigEntry('base_path'),
 769                         $this->getGenericBasePath(),
 770                         'menus/_cache',
 771                         md5(
 772                                 $this->getMenuInstance()->getMenuName() . ':' .
 773                                 $this->__toString() . ':' .
 774                                 $this->getMenuInstance()->__toString()
 775                         ),
 776                         $this->getMenuInstance()->getMenuType()
 777                 );
 778
 779                 // Return it
 780                 return $fqfn;
 781         }
 782 }
 783
 784 // [EOF]
 785 ?>