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                 'entries-content',
  39                 'header',
  40                 'footer',
  41                 'block',
  42                 'title',
  43                 'anchor',
  44                 'design',
  45                 'text',
  46                 'advert',
  47         );
  48
  49         /**
  50          * Menu instance
  51          */
  52         private $menuInstance = null;
  53
  54         /**
  55          * Current main node
  56          */
  57         private $curr = array();
  58
  59         /**
  60          * Content from depency
  61          */
  62         private $depencyContent = array();
  63
  64         /**
  65          * Protected constructor
  66          *
  67          * @return      void
  68          */
  69         protected function __construct () {
  70                 // Call parent constructor
  71                 parent::__construct(__CLASS__);
  72         }
  73
  74         /**
  75          * Creates an instance of the class TemplateEngine and prepares it for usage
  76          *
  77          * @param       $appInstance    A manageable application
  78          * @param       $menuInstance   A RenderableMenu instance
  79          * @return      $tplInstance    An instance of TemplateEngine
  80          * @throws      BasePathIsEmptyException                If the provided $templateBasePath is empty
  81          * @throws      InvalidBasePathStringException  If $templateBasePath is no string
  82          * @throws      BasePathIsNoDirectoryException  If $templateBasePath is no
  83          *                                                                                      directory or not found
  84          * @throws      BasePathReadProtectedException  If $templateBasePath is
  85          *                                                                                      read-protected
  86          */
  87         public final static function createMenuTemplateEngine (ManageableApplication $appInstance, RenderableMenu $menuInstance) {
  88                 // Get a new instance
  89                 $tplInstance = new MenuTemplateEngine();
  90
  91                 // Get language and file I/O instances from application
  92                 $langInstance = $appInstance->getLanguageInstance();
  93                 $ioInstance = $appInstance->getFileIoInstance();
  94
  95                 // Determine base path
  96                 $templateBasePath = $tplInstance->getConfigInstance()->getConfigEntry('application_base_path') . $appInstance->getRequestInstance()->getRequestElement('app') . '/';
  97
  98                 // Is the base path valid?
  99                 if (empty($templateBasePath)) {
 100                         // Base path is empty
 101                         throw new BasePathIsEmptyException($tplInstance, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 102                 } elseif (!is_string($templateBasePath)) {
 103                         // Is not a string
 104                         throw new InvalidBasePathStringException(array($tplInstance, $templateBasePath), self::EXCEPTION_INVALID_STRING);
 105                 } elseif (!is_dir($templateBasePath)) {
 106                         // Is not a path
 107                         throw new BasePathIsNoDirectoryException(array($tplInstance, $templateBasePath), self::EXCEPTION_INVALID_PATH_NAME);
 108                 } elseif (!is_readable($templateBasePath)) {
 109                         // Is not readable
 110                         throw new BasePathReadProtectedException(array($tplInstance, $templateBasePath), self::EXCEPTION_READ_PROTECED_PATH);
 111                 }
 112
 113                 // Get configuration instance
 114                 $configInstance = FrameworkConfiguration::getInstance();
 115
 116                 // Set the base path
 117                 $tplInstance->setTemplateBasePath($templateBasePath);
 118
 119                 // Set the language and IO instances
 120                 $tplInstance->setLanguageInstance($langInstance);
 121                 $tplInstance->setFileIoInstance($ioInstance);
 122
 123                 // Set template extensions
 124                 $tplInstance->setRawTemplateExtension($configInstance->getConfigEntry('raw_template_extension'));
 125                 $tplInstance->setCodeTemplateExtension($configInstance->getConfigEntry('menu_template_extension'));
 126
 127                 // Absolute output path for compiled templates
 128                 $tplInstance->setCompileOutputPath($configInstance->getConfigEntry('base_path') . $configInstance->getConfigEntry('compile_output_path'));
 129
 130                 // Set the menu instance
 131                 $tplInstance->setMenuInstance($menuInstance);
 132
 133                 // Return the prepared instance
 134                 return $tplInstance;
 135         }
 136
 137         /**
 138          * Load a specified menu template into the engine
 139          *
 140          * @param       $template       The menu template we shall load which is
 141          *                                              located in 'menu' by default
 142          * @return      void
 143          */
 144         public function loadMenuTemplate ($template) {
 145                 // Set template type
 146                 $this->setTemplateType($this->getConfigInstance()->getConfigEntry('menu_template_type'));
 147
 148                 // Load the special template
 149                 $this->loadTemplate($template);
 150         }
 151
 152         /**
 153          * Getter for current main node
 154          *
 155          * @return      $currMainNode   Current main node
 156          */
 157         public final function getCurrMainNode () {
 158                 return $this->curr['main_node'];
 159         }
 160
 161         /**
 162          * Setter for current main node
 163          *
 164          * @param       $element                Element name to set as current main node
 165          * @return      $currMainNode   Current main node
 166          */
 167         private final function setCurrMainNode ($element) {
 168                 $this->curr['main_node'] = (string) $element;
 169         }
 170
 171         /**
 172          * Getter for main node array
 173          *
 174          * @return      $mainNodes      Array with valid main node names
 175          */
 176         public final function getMainNodes () {
 177                 return $this->mainNodes;
 178         }
 179
 180         /**
 181          * Getter for sub node array
 182          *
 183          * @return      $subNodes       Array with valid sub node names
 184          */
 185         public final function getSubNodes () {
 186                 return $this->subNodes;
 187         }
 188
 189         /**
 190          * Handles the start element of an XML resource
 191          *
 192          * @param       $resource               XML parser resource (currently ignored)
 193          * @param       $element                The element we shall handle
 194          * @param       $attributes             All attributes
 195          * @return      void
 196          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
 197          */
 198         public function startElement ($resource, $element, array $attributes) {
 199                 // Initial method name which will never be called...
 200                 $methodName = 'initMenu';
 201
 202                 // Make the element name lower-case
 203                 $element = strtolower($element);
 204
 205                 // Is the element a main node?
 206                 //* DEBUG: */ echo "START: &gt;".$element."&lt;<br />\n";
 207                 if (in_array($element, $this->getMainNodes())) {
 208                         // Okay, main node found!
 209                         $methodName = 'start' . $this->convertToClassName($element);
 210
 211                         // Set it
 212                         $this->setCurrMainNode($element);
 213                 } elseif (in_array($element, $this->getSubNodes())) {
 214                         // Sub node found
 215                         $methodName = 'start' . $this->convertToClassName($element);
 216                 } elseif ($element != 'menu') {
 217                         // Invalid node name found
 218                         throw new InvalidXmlNodeException(array($this, $element, $attributes), XmlParser::EXCEPTION_XML_NODE_UNKNOWN);
 219                 }
 220
 221                 // Call method
 222                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 223                 call_user_func_array(array($this, $methodName), $attributes);
 224         }
 225
 226         /**
 227          * Ends the main or sub node by sending out the gathered data
 228          *
 229          * @param       $resource       An XML resource pointer (currently ignored)
 230          * @param       $nodeName       Name of the node we want to finish
 231          * @return      void
 232          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
 233          */
 234         public function endElement ($resource, $nodeName) {
 235                 // Make all lower-case
 236                 $nodeName = strtolower($nodeName);
 237
 238                 // Does this match with current main node?
 239                 //* DEBUG: */ echo "END: &gt;".$nodeName."&lt;<br />\n";
 240                 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
 241                         // Did not match!
 242                         throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), XmlParser::EXCEPTION_XML_NODE_MISMATCH);
 243                 } // END - if
 244
 245                 // Construct method name
 246                 $methodName = 'finish' . $this->convertToClassName($nodeName);
 247
 248                 // Call the corresponding method
 249                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 250                 call_user_func_array(array($this, $methodName), array());
 251         }
 252
 253         /**
 254          * Currently not used
 255          *
 256          * @param       $resource               XML parser resource (currently ignored)
 257          * @param       $characters             Characters to handle
 258          * @return      void
 259          * @todo        Find something useful with this!
 260          */
 261         public function characterHandler ($resource, $characters) {
 262                 // Trim all spaces away
 263                 $characters = trim($characters);
 264
 265                 // Is this string empty?
 266                 if (empty($characters)) {
 267                         // Then skip it silently
 268                         return false;
 269                 } // END - if
 270
 271                 // Unfinished work!
 272                 $this->partialStub('Handling extra characters is not yet supported! length='.strlen($characters));
 273         }
 274
 275         /**
 276          * Handles the template depency for given node
 277          *
 278          * @param       $node   The node we should load a depency template
 279          * @param       $templateDepency        A template to load to satisfy depencies
 280          * @return      void
 281          */
 282         private function handleTemplateDepency ($node, $templateDepency) {
 283                 // Is the template depency set?
 284                 if ((!empty($templateDepency)) && (!isset($this->depencyContent[$node]))) {
 285                         // Get a temporay menu template instance
 286                         $templateInstance = ObjectFactory::createObjectByConfiguredName('menu_template_class', array($this->getApplicationInstance(), $this->getMenuInstance()));
 287
 288                         // Then load it
 289                         $templateInstance->loadMenuTemplate($templateDepency);
 290
 291                         // Get an XmlParser instance
 292                         $templateInstance->renderXmlContent();
 293
 294                         // Parse the template's content contents
 295                         $this->depencyContent[$node] = $templateInstance->getRawTemplateData();
 296                 } // END - if
 297         }
 298
 299         /**
 300          * Intializes the menu
 301          *
 302          * @param       $templateDepency        A template to load to satisfy depencies
 303          * @return      void
 304          * @todo        Add cache creation here
 305          */
 306         private function initMenu ($templateDepency = '') {
 307                 // Get web template engine
 308                 $this->setTemplateInstance(ObjectFactory::createObjectByConfiguredName('web_template_class', array($this->getApplicationInstance())));
 309
 310                 // Handle the depency template
 311                 $this->handleTemplateDepency('menu', $templateDepency);
 312
 313                 // Load the header template for this page
 314                 $this->getTemplateInstance()->loadCodeTemplate('menu_global_start');
 315
 316                 // Set the variable group to page
 317                 $this->setVariableGroup('menu');
 318
 319                 // Set its content in this template instance
 320                 $this->assignVariable('menu_start', $this->getTemplateInstance()->getRawTemplateData());
 321         }
 322
 323         /**
 324          * Finishes the menu
 325          *
 326          * @return      void
 327          */
 328         private function finishMenu () {
 329                 // Load the header template for this page
 330                 $this->getTemplateInstance()->loadCodeTemplate('menu_global_end');
 331
 332                 // Set the variable group to page
 333                 $this->setVariableGroup('menu');
 334
 335                 // Set its content in this template instance
 336                 $this->assignVariable('menu_end', $this->getTemplateInstance()->getRawTemplateData());
 337         }
 338
 339         /**
 340          * Starts the menu entries by loading a (maybe) provided template depency
 341          *
 342          * @param       $templateDepency        A template to load to satisfy depencies
 343          * @return      void
 344          */
 345         private function startEntryList ($templateDepency = '') {
 346                 // Handle the depency template
 347                 $this->handleTemplateDepency('entries', $templateDepency);
 348
 349                 // Load the header template for this page
 350                 $this->getTemplateInstance()->loadCodeTemplate('menu_entries_start');
 351
 352                 // Set the variable group to page
 353                 $this->setVariableGroup('menu');
 354
 355                 // Set its content in this template instance
 356                 $this->assignVariable('entries_start', $this->getTemplateInstance()->getRawTemplateData());
 357         }
 358
 359         /**
 360          * Finishes the menu entries
 361          *
 362          * @return      void
 363          */
 364         private function finishEntryList () {
 365                 // Load the header template for this page
 366                 $this->getTemplateInstance()->loadCodeTemplate('menu_entries_end');
 367
 368                 // Set the variable group to page
 369                 $this->setVariableGroup('menu');
 370
 371                 // Set its content in this template instance
 372                 $this->assignVariable('entries_end', $this->getTemplateInstance()->getRawTemplateData());
 373         }
 374
 375         /**
 376          * Starts the menu header
 377          *
 378          * @return      void
 379          */
 380         private function startHeader () {
 381                 // Do we have a template instance?
 382                 if (is_null($this->getTemplateInstance())) {
 383                         // Init template instance for underlaying web templates
 384                         $templateInstance = ObjectFactory::createObjectByConfiguredName('web_template_class');
 385
 386                         // Set it in this template engine
 387                         $this->setTemplateInstance($templateInstance);
 388                 } // END - if
 389
 390                 // Load the header template for this page
 391                 $this->getTemplateInstance()->loadCodeTemplate('menu_header_start');
 392
 393                 // Set the variable group to page
 394                 $this->setVariableGroup('menu');
 395
 396                 // Set its content in this template instance
 397                 $this->assignVariable('header', $this->getTemplateInstance()->getRawTemplateData());
 398         }
 399
 400         /**
 401          * Finishes the menu header
 402          *
 403          * @return      void
 404          */
 405         private function finishHeader () {
 406                 // Load the header template for this page
 407                 $this->getTemplateInstance()->loadCodeTemplate('menu_header_end');
 408
 409                 // Set the variable group to page
 410                 $this->setVariableGroup('menu');
 411
 412                 // Set its content in this template instance
 413                 $this->assignVariable('header_end', $this->getTemplateInstance()->getRawTemplateData());
 414         }
 415
 416         /**
 417          * Starts the menu footer
 418          *
 419          * @return      void
 420          */
 421         private function startFooter () {
 422                 // Do we have a template instance?
 423                 if (is_null($this->getTemplateInstance())) {
 424                         // Init template instance for underlaying web templates
 425                         $templateInstance = ObjectFactory::createObjectByConfiguredName('web_template_class');
 426
 427                         // Set it in this template engine
 428                         $this->setTemplateInstance($templateInstance);
 429                 } // END - if
 430
 431                 // Load the footer template for this page
 432                 $this->getTemplateInstance()->loadCodeTemplate('menu_footer_start');
 433
 434                 // Set the variable group to page
 435                 $this->setVariableGroup('menu');
 436
 437                 // Set its content in this template instance
 438                 $this->assignVariable('footer', $this->getTemplateInstance()->getRawTemplateData());
 439         }
 440
 441         /**
 442          * Finishes the menu footer
 443          *
 444          * @return      void
 445          */
 446         private function finishFooter () {
 447                 // Load the footer template for this page
 448                 $this->getTemplateInstance()->loadCodeTemplate('menu_footer_end');
 449
 450                 // Set the variable group to page
 451                 $this->setVariableGroup('menu');
 452
 453                 // Set its content in this template instance
 454                 $this->assignVariable('footer_end', $this->getTemplateInstance()->getRawTemplateData());
 455         }
 456
 457         /**
 458          * Starts the menu property 'title'
 459          *
 460          * @param       $id             Id of the menu
 461          * @param       $class  The title to add to the menu
 462          * @return      void
 463          */
 464         private function startTitle ($id, $class) {
 465                 // Set id as current
 466                 $this->curr['id'] = $id;
 467
 468                 // Load the title template for this page
 469                 $this->getTemplateInstance()->loadCodeTemplate('menu_title_' . $id . '_start');
 470
 471                 // Set the variable group to page
 472                 $this->setVariableGroup('menu');
 473
 474                 // Set its content in this template instance
 475                 $this->assignVariable('title_start_' . $this->curr['id'], $this->getTemplateInstance()->getRawTemplateData());
 476         }
 477
 478         /**
 479          * Finishes the title node by added another template to the menu
 480          *
 481          * @return      void
 482          */
 483         private function finishTitle () {
 484                 // Load the title template for this page
 485                 $this->getTemplateInstance()->loadCodeTemplate('menu_title_' . $this->curr['id'] . '_end');
 486
 487                 // Set the variable group to page
 488                 $this->setVariableGroup('menu');
 489
 490                 // Set its content in this template instance
 491                 $this->assignVariable('title_end_' . $this->curr['id'], $this->getTemplateInstance()->getRawTemplateData());
 492         }
 493
 494         /**
 495          * Starts the menu text
 496          *
 497          * @return      void
 498          */
 499         private function startText () {
 500                 // Do we have a template instance?
 501                 if (is_null($this->getTemplateInstance())) {
 502                         // Init template instance for underlaying web templates
 503                         $templateInstance = ObjectFactory::createObjectByConfiguredName('web_template_class');
 504
 505                         // Set it in this template engine
 506                         $this->setTemplateInstance($templateInstance);
 507                 } // END - if
 508
 509                 // Load the text template for this page
 510                 $this->getTemplateInstance()->loadCodeTemplate('menu_text_start');
 511
 512                 // Set the variable group to page
 513                 $this->setVariableGroup('menu');
 514
 515                 // Set its content in this template instance
 516                 $this->assignVariable('text', $this->getTemplateInstance()->getRawTemplateData());
 517         }
 518
 519         /**
 520          * Finishes the menu text
 521          *
 522          * @return      void
 523          */
 524         private function finishText () {
 525                 // Load the text template for this page
 526                 $this->getTemplateInstance()->loadCodeTemplate('menu_text_end');
 527
 528                 // Set the variable group to page
 529                 $this->setVariableGroup('menu');
 530
 531                 // Set its content in this template instance
 532                 $this->assignVariable('text_end', $this->getTemplateInstance()->getRawTemplateData());
 533         }
 534
 535         /**
 536          * Starts the menu property 'entry'
 537          *
 538          * @param       $id             Id of the menu
 539          * @return      void
 540          */
 541         private function startEntry ($id) {
 542                 // Set id as current
 543                 $this->curr['entry_id'] = $id;
 544
 545                 // Load the entry template for this page
 546                 $this->getTemplateInstance()->loadCodeTemplate('menu_entry_' . $id . '_start');
 547
 548                 // Set the variable group to page
 549                 $this->setVariableGroup('menu');
 550
 551                 // Set its content in this template instance
 552                 $this->assignVariable('entry_start_' . $this->curr['id'], $this->getTemplateInstance()->getRawTemplateData());
 553         }
 554
 555         /**
 556          * Finishes the entry node by added another template to the menu
 557          *
 558          * @return      void
 559          */
 560         private function finishEntry () {
 561                 // Load the entry template for this page
 562                 $this->getTemplateInstance()->loadCodeTemplate('menu_entry_' . $this->curr['entry_id'] . '_end');
 563
 564                 // Set the variable group to page
 565                 $this->setVariableGroup('menu');
 566
 567                 // Set its content in this template instance
 568                 $this->assignVariable('entry_end_' . $this->curr['id'], $this->getTemplateInstance()->getRawTemplateData());
 569         }
 570         /**
 571          * Starts the menu property 'anchor'
 572          *
 573          * @param       $id             Id of the anchor
 574          * @param       $link   Link text of the anchor
 575          * @param       $title  Link title of the anchor
 576          * @return      void
 577          */
 578         private function startAnchor ($id, $link, $title) {
 579                 $this->partialStub('id='.$id.',link='.$link.',title='.$title);
 580         }
 581
 582         /**
 583          * Finishes the anchor node by added another template to the menu
 584          *
 585          * @return      void
 586          */
 587         private function finishAnchor () {
 588                 $this->partialStub('Please implement this method.');
 589         }
 590
 591         /**
 592          * Getter for menu cache file (FQFN)
 593          *
 594          * @return      $fqfn   Full-qualified file name of the menu cache
 595          */
 596         public function getMenuCacheFqfn () {
 597                 // Get the FQFN ready
 598                 $fqfn = sprintf("%s%s%s/%s.%s",
 599                         $this->getConfigInstance()->getConfigEntry('base_path'),
 600                         $this->getGenericBasePath(),
 601                         'menus/_cache',
 602                         md5(
 603                                 $this->getMenuInstance()->getMenuName() . ':' .
 604                                 $this->__toString() . ':' .
 605                                 $this->getMenuInstance()->__toString()
 606                         ),
 607                         $this->getMenuInstance()->getMenuType()
 608                 );
 609
 610                 // Return it
 611                 return $fqfn;
 612         }
 613 }
 614
 615 // [EOF]
 616 ?>