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                 'header',
  41                 '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 depency
  72          */
  73         private $depencyContent = 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                 // Return the prepared instance
 145                 return $tplInstance;
 146         }
 147
 148         /**
 149          * Load a specified menu template into the engine
 150          *
 151          * @param       $template       The menu template we shall load which is
 152          *                                              located in 'menu' by default
 153          * @return      void
 154          */
 155         public function loadMenuTemplate ($template) {
 156                 // Set template type
 157                 $this->setTemplateType($this->getConfigInstance()->getConfigEntry('menu_template_type'));
 158
 159                 // Load the special template
 160                 $this->loadTemplate($template);
 161         }
 162
 163         /**
 164          * Getter for current main node
 165          *
 166          * @return      $currMainNode   Current main node
 167          */
 168         public final function getCurrMainNode () {
 169                 return $this->curr['main_node'];
 170         }
 171
 172         /**
 173          * Setter for current main node
 174          *
 175          * @param       $element                Element name to set as current main node
 176          * @return      $currMainNode   Current main node
 177          */
 178         private final function setCurrMainNode ($element) {
 179                 $this->curr['main_node'] = (string) $element;
 180         }
 181
 182         /**
 183          * Getter for main node array
 184          *
 185          * @return      $mainNodes      Array with valid main node names
 186          */
 187         public final function getMainNodes () {
 188                 return $this->mainNodes;
 189         }
 190
 191         /**
 192          * Getter for sub node array
 193          *
 194          * @return      $subNodes       Array with valid sub node names
 195          */
 196         public final function getSubNodes () {
 197                 return $this->subNodes;
 198         }
 199
 200         /**
 201          * Handles the start element of an XML resource
 202          *
 203          * @param       $resource               XML parser resource (currently ignored)
 204          * @param       $element                The element we shall handle
 205          * @param       $attributes             All attributes
 206          * @return      void
 207          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
 208          */
 209         public function startElement ($resource, $element, array $attributes) {
 210                 // Initial method name which will never be called...
 211                 $methodName = 'initMenu';
 212
 213                 // Make the element name lower-case
 214                 $element = strtolower($element);
 215
 216                 // Is the element a main node?
 217                 //* DEBUG: */ echo "START: &gt;".$element."&lt;<br />\n";
 218                 if (in_array($element, $this->getMainNodes())) {
 219                         // Okay, main node found!
 220                         $methodName = 'start' . $this->convertToClassName($element);
 221
 222                         // Set it
 223                         $this->setCurrMainNode($element);
 224                 } elseif (in_array($element, $this->getSubNodes())) {
 225                         // Sub node found
 226                         $methodName = 'start' . $this->convertToClassName($element);
 227                 } elseif ($element != 'menu') {
 228                         // Invalid node name found
 229                         throw new InvalidXmlNodeException(array($this, $element, $attributes), XmlParser::EXCEPTION_XML_NODE_UNKNOWN);
 230                 }
 231
 232                 // Call method
 233                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 234                 call_user_func_array(array($this, $methodName), $attributes);
 235         }
 236
 237         /**
 238          * Ends the main or sub node by sending out the gathered data
 239          *
 240          * @param       $resource       An XML resource pointer (currently ignored)
 241          * @param       $nodeName       Name of the node we want to finish
 242          * @return      void
 243          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
 244          */
 245         public function endElement ($resource, $nodeName) {
 246                 // Make all lower-case
 247                 $nodeName = strtolower($nodeName);
 248
 249                 // Does this match with current main node?
 250                 //* DEBUG: */ echo "END: &gt;".$nodeName."&lt;<br />\n";
 251                 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
 252                         // Did not match!
 253                         throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), XmlParser::EXCEPTION_XML_NODE_MISMATCH);
 254                 } // END - if
 255
 256                 // Construct method name
 257                 $methodName = 'finish' . $this->convertToClassName($nodeName);
 258
 259                 // Call the corresponding method
 260                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 261                 call_user_func_array(array($this, $methodName), array());
 262         }
 263
 264         /**
 265          * Currently not used
 266          *
 267          * @param       $resource               XML parser resource (currently ignored)
 268          * @param       $characters             Characters to handle
 269          * @return      void
 270          * @todo        Find something useful with this!
 271          */
 272         public function characterHandler ($resource, $characters) {
 273                 // Trim all spaces away
 274                 $characters = trim($characters);
 275
 276                 // Is this string empty?
 277                 if (empty($characters)) {
 278                         // Then skip it silently
 279                         return false;
 280                 } // END - if
 281
 282                 // Unfinished work!
 283                 $this->partialStub('Handling extra characters is not yet supported! length='.strlen($characters));
 284         }
 285
 286         /**
 287          * Handles the template depency for given node
 288          *
 289          * @param       $node   The node we should load a depency template
 290          * @param       $templateDepency        A template to load to satisfy depencies
 291          * @return      void
 292          */
 293         private function handleTemplateDepency ($node, $templateDepency) {
 294                 // Is the template depency set?
 295                 if ((!empty($templateDepency)) && (!isset($this->depencyContent[$node]))) {
 296                         // Get a temporay menu template instance
 297                         $templateInstance = ObjectFactory::createObjectByConfiguredName('menu_template_class', array($this->getApplicationInstance(), $this->getMenuInstance()));
 298
 299                         // Then load it
 300                         $templateInstance->loadMenuTemplate($templateDepency);
 301
 302                         // Get an XmlParser instance
 303                         $templateInstance->renderXmlContent();
 304
 305                         // Parse the template's content contents
 306                         $this->depencyContent[$node] = $templateInstance->getRawTemplateData();
 307                 } // END - if
 308         }
 309
 310         /**
 311          * Intializes the menu
 312          *
 313          * @param       $templateDepency        A template to load to satisfy depencies
 314          * @return      void
 315          * @todo        Add cache creation here
 316          */
 317         private function initMenu ($templateDepency = '') {
 318                 // Get web template engine
 319                 $this->setTemplateInstance(ObjectFactory::createObjectByConfiguredName('web_template_class', array($this->getApplicationInstance())));
 320
 321                 // Handle the depency template
 322                 $this->handleTemplateDepency('menu', $templateDepency);
 323
 324                 // Load the header template for this page
 325                 $this->getTemplateInstance()->loadCodeTemplate('menu_global_start');
 326
 327                 // Set the variable group to page
 328                 $this->setVariableGroup('menu');
 329
 330                 // Set its content in this template instance
 331                 $this->assignVariable('menu_start', $this->getTemplateInstance()->getRawTemplateData());
 332         }
 333
 334         /**
 335          * Finishes the menu
 336          *
 337          * @return      void
 338          */
 339         private function finishMenu () {
 340                 // Load the header template for this page
 341                 $this->getTemplateInstance()->loadCodeTemplate('menu_global_end');
 342
 343                 // Set the variable group to page
 344                 $this->setVariableGroup('menu');
 345
 346                 // Set its content in this template instance
 347                 $this->assignVariable('menu_end', $this->getTemplateInstance()->getRawTemplateData());
 348         }
 349
 350         /**
 351          * Starts the menu entries by loading a (maybe) provided template depency
 352          *
 353          * @param       $templateDepency        A template to load to satisfy depencies
 354          * @return      void
 355          */
 356         private function startEntryList ($templateDepency = '') {
 357                 // Handle the depency template
 358                 $this->handleTemplateDepency('entries', $templateDepency);
 359
 360                 // Load the header template for this page
 361                 $this->getTemplateInstance()->loadCodeTemplate('menu_entries_start');
 362
 363                 // Set the variable group to page
 364                 $this->setVariableGroup('menu');
 365
 366                 // Set its content in this template instance
 367                 $this->assignVariable('entries_start', $this->getTemplateInstance()->getRawTemplateData());
 368         }
 369
 370         /**
 371          * Finishes the menu entries
 372          *
 373          * @return      void
 374          */
 375         private function finishEntryList () {
 376                 // Load the header template for this page
 377                 $this->getTemplateInstance()->loadCodeTemplate('menu_entries_end');
 378
 379                 // Set the variable group to page
 380                 $this->setVariableGroup('menu');
 381
 382                 // Set its content in this template instance
 383                 $this->assignVariable('entries_end', $this->getTemplateInstance()->getRawTemplateData());
 384         }
 385
 386         /**
 387          * Starts the menu header
 388          *
 389          * @return      void
 390          */
 391         private function startHeader () {
 392                 // Do we have a template instance?
 393                 if (is_null($this->getTemplateInstance())) {
 394                         // Init template instance for underlaying web templates
 395                         $templateInstance = ObjectFactory::createObjectByConfiguredName('web_template_class');
 396
 397                         // Set it in this template engine
 398                         $this->setTemplateInstance($templateInstance);
 399                 } // END - if
 400
 401                 // Load the header template for this page
 402                 $this->getTemplateInstance()->loadCodeTemplate('menu_header_start');
 403
 404                 // Set the variable group to page
 405                 $this->setVariableGroup('menu');
 406
 407                 // Set its content in this template instance
 408                 $this->assignVariable('header', $this->getTemplateInstance()->getRawTemplateData());
 409         }
 410
 411         /**
 412          * Finishes the menu header
 413          *
 414          * @return      void
 415          */
 416         private function finishHeader () {
 417                 // Load the header template for this page
 418                 $this->getTemplateInstance()->loadCodeTemplate('menu_header_end');
 419
 420                 // Set the variable group to page
 421                 $this->setVariableGroup('menu');
 422
 423                 // Set its content in this template instance
 424                 $this->assignVariable('header_end', $this->getTemplateInstance()->getRawTemplateData());
 425         }
 426
 427         /**
 428          * Starts the menu footer
 429          *
 430          * @return      void
 431          */
 432         private function startFooter () {
 433                 // Do we have a template instance?
 434                 if (is_null($this->getTemplateInstance())) {
 435                         // Init template instance for underlaying web templates
 436                         $templateInstance = ObjectFactory::createObjectByConfiguredName('web_template_class');
 437
 438                         // Set it in this template engine
 439                         $this->setTemplateInstance($templateInstance);
 440                 } // END - if
 441
 442                 // Load the footer template for this page
 443                 $this->getTemplateInstance()->loadCodeTemplate('menu_footer_start');
 444
 445                 // Set the variable group to page
 446                 $this->setVariableGroup('menu');
 447
 448                 // Set its content in this template instance
 449                 $this->assignVariable('footer', $this->getTemplateInstance()->getRawTemplateData());
 450         }
 451
 452         /**
 453          * Finishes the menu footer
 454          *
 455          * @return      void
 456          */
 457         private function finishFooter () {
 458                 // Load the footer template for this page
 459                 $this->getTemplateInstance()->loadCodeTemplate('menu_footer_end');
 460
 461                 // Set the variable group to page
 462                 $this->setVariableGroup('menu');
 463
 464                 // Set its content in this template instance
 465                 $this->assignVariable('footer_end', $this->getTemplateInstance()->getRawTemplateData());
 466         }
 467
 468         /**
 469          * Starts the menu property 'title'
 470          *
 471          * @return      void
 472          */
 473         private function startTitle () {
 474                 $this->partialStub('Cleared due to XML rewrite.');
 475         }
 476
 477         /**
 478          * Finishes the title node by added another template to the menu
 479          *
 480          * @return      void
 481          */
 482         private function finishTitle () {
 483                 $this->partialStub('Cleared due to XML rewrite.');
 484         }
 485
 486         /**
 487          * Starts the menu text
 488          *
 489          * @return      void
 490          */
 491         private function startText () {
 492                 // Do we have a template instance?
 493                 if (is_null($this->getTemplateInstance())) {
 494                         // Init template instance for underlaying web templates
 495                         $templateInstance = ObjectFactory::createObjectByConfiguredName('web_template_class');
 496
 497                         // Set it in this template engine
 498                         $this->setTemplateInstance($templateInstance);
 499                 } // END - if
 500
 501                 // Load the text template for this page
 502                 $this->getTemplateInstance()->loadCodeTemplate('menu_text_start');
 503
 504                 // Set the variable group to page
 505                 $this->setVariableGroup('menu');
 506
 507                 // Set its content in this template instance
 508                 $this->assignVariable('text', $this->getTemplateInstance()->getRawTemplateData());
 509         }
 510
 511         /**
 512          * Finishes the menu text
 513          *
 514          * @return      void
 515          */
 516         private function finishText () {
 517                 // Load the text template for this page
 518                 $this->getTemplateInstance()->loadCodeTemplate('menu_text_end');
 519
 520                 // Set the variable group to page
 521                 $this->setVariableGroup('menu');
 522
 523                 // Set its content in this template instance
 524                 $this->assignVariable('text_end', $this->getTemplateInstance()->getRawTemplateData());
 525         }
 526
 527         /**
 528          * Starts the menu property 'entry'
 529          *
 530          * @return      void
 531          */
 532         private function startEntry () {
 533                 $this->partialStub('Cleared due to XML rewrite.');
 534         }
 535
 536         /**
 537          * Finishes the entry node by added another template to the menu
 538          *
 539          * @return      void
 540          */
 541         private function finishEntry () {
 542                 $this->partialStub('Cleared due to XML rewrite.');
 543         }
 544
 545         /**
 546          * Starts the menu property 'anchor'
 547          *
 548          * @param       $id             Id of the anchor
 549          * @param       $link   Link text of the anchor
 550          * @param       $title  Link title of the anchor
 551          * @return      void
 552          */
 553         private function startAnchor () {
 554                 $this->partialStub('Please implement this method.');
 555         }
 556
 557         /**
 558          * Finishes the anchor node by added another template to the menu
 559          *
 560          * @return      void
 561          */
 562         private function finishAnchor () {
 563                 $this->partialStub('Please implement this method.');
 564         }
 565
 566         /**
 567          * Getter for menu cache file (FQFN)
 568          *
 569          * @return      $fqfn   Full-qualified file name of the menu cache
 570          */
 571         public function getMenuCacheFqfn () {
 572                 // Get the FQFN ready
 573                 $fqfn = sprintf("%s%s%s/%s.%s",
 574                         $this->getConfigInstance()->getConfigEntry('base_path'),
 575                         $this->getGenericBasePath(),
 576                         'menus/_cache',
 577                         md5(
 578                                 $this->getMenuInstance()->getMenuName() . ':' .
 579                                 $this->__toString() . ':' .
 580                                 $this->getMenuInstance()->__toString()
 581                         ),
 582                         $this->getMenuInstance()->getMenuType()
 583                 );
 584
 585                 // Return it
 586                 return $fqfn;
 587         }
 588 }
 589
 590 // [EOF]
 591 ?>