Anchors has no longer arguments
[core.git] / 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 () {
579                 $this->partialStub('Please implement this method.');
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 ?>