Refactured code for deprecated includes file_io and language:
[core.git] / inc / classes / main / template / image / class_ImageTemplateEngine.php
1 <?php
2 /**
3  * The own template engine for loading caching and sending out images
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 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 ImageTemplateEngine extends BaseTemplateEngine implements CompileableTemplate {
25         /**
26          * Main nodes in the XML tree ('image' is ignored)
27          */
28         private $mainNodes = array(
29                 'base',
30                 'type',
31                 'resolution',
32                 'background-color',
33                 'foreground-color',
34                 'image-string'
35         );
36
37         /**
38          * Sub nodes in the XML tree
39          */
40         private $subNodes = array(
41                 'name',
42                 'string-name',
43                 'x',
44                 'y',
45                 'font-size',
46                 'width',
47                 'height',
48                 'red',
49                 'green',
50                 'blue',
51                 'text'
52         );
53
54         /**
55          * Current main node
56          */
57         private $currMainNode = '';
58
59         /**
60          * Protected constructor
61          *
62          * @return      void
63          */
64         protected function __construct () {
65                 // Call parent constructor
66                 parent::__construct(__CLASS__);
67         }
68
69         /**
70          * Creates an instance of the class TemplateEngine and prepares it for usage
71          *
72          * @param       $appInstance    A manageable application
73          * @return      $templateInstance       An instance of TemplateEngine
74          * @throws      BasePathIsEmptyException                If the provided $templateBasePath is empty
75          * @throws      InvalidBasePathStringException  If $templateBasePath is no string
76          * @throws      BasePathIsNoDirectoryException  If $templateBasePath is no
77          *                                                                                      directory or not found
78          * @throws      BasePathReadProtectedException  If $templateBasePath is
79          *                                                                                      read-protected
80          */
81         public static final function createImageTemplateEngine (ManageableApplication $appInstance) {
82                 // Get a new instance
83                 $templateInstance = new ImageTemplateEngine();
84
85                 // Determine base path
86                 $templateBasePath = $templateInstance->getConfigInstance()->getConfigEntry('application_base_path') . $appInstance->getRequestInstance()->getRequestElement('app') . '/';
87
88                 // Is the base path valid?
89                 if (empty($templateBasePath)) {
90                         // Base path is empty
91                         throw new BasePathIsEmptyException($templateInstance, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
92                 } elseif (!is_string($templateBasePath)) {
93                         // Is not a string
94                         throw new InvalidBasePathStringException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_STRING);
95                 } elseif (!is_dir($templateBasePath)) {
96                         // Is not a path
97                         throw new BasePathIsNoDirectoryException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_PATH_NAME);
98                 } elseif (!is_readable($templateBasePath)) {
99                         // Is not readable
100                         throw new BasePathReadProtectedException(array($templateInstance, $templateBasePath), self::EXCEPTION_READ_PROTECED_PATH);
101                 }
102
103                 // Set the base path
104                 $templateInstance->setTemplateBasePath($templateBasePath);
105
106                 // Set template extensions
107                 $templateInstance->setRawTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('raw_template_extension'));
108                 $templateInstance->setCodeTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('code_template_extension'));
109
110                 // Absolute output path for compiled templates
111                 $templateInstance->setCompileOutputPath($templateInstance->getConfigInstance()->getConfigEntry('base_path') . $templateInstance->getConfigInstance()->getConfigEntry('compile_output_path'));
112
113                 // Return the prepared instance
114                 return $templateInstance;
115         }
116
117         /**
118          * Getter for current main node
119          *
120          * @return      $currMainNode   Current main node
121          */
122         public final function getCurrMainNode () {
123                 return $this->currMainNode;
124         }
125
126         /**
127          * Getter for main node array
128          *
129          * @return      $mainNodes      Array with valid main node names
130          */
131         public final function getMainNodes () {
132                 return $this->mainNodes;
133         }
134
135         /**
136          * Getter for sub node array
137          *
138          * @return      $subNodes       Array with valid sub node names
139          */
140         public final function getSubNodes () {
141                 return $this->subNodes;
142         }
143
144         /**
145          * Handles the start element of an XML resource
146          *
147          * @param       $resource               XML parser resource (currently ignored)
148          * @param       $element                The element we shall handle
149          * @param       $attributes             All attributes
150          * @return      void
151          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
152          */
153         public function startElement ($resource, $element, array $attributes) {
154                 // Initial method name which will never be called...
155                 $methodName = 'initImage';
156
157                 // Make the element name lower-case
158                 $element = strtolower($element);
159
160                 // Is the element a main node?
161                 //* DEBUG: */ echo "START: &gt;".$element."&lt;<br />\n";
162                 if (in_array($element, $this->mainNodes)) {
163                         // Okay, main node found!
164                         $methodName = 'setImage' . $this->convertToClassName($element);
165                 } elseif (in_array($element, $this->subNodes)) {
166                         // Sub node found
167                         $methodName = 'setImageProperty' . $this->convertToClassName($element);
168                 } elseif ($element != 'image') {
169                         // Invalid node name found
170                         throw new InvalidXmlNodeException(array($this, $element, $attributes), XmlParser::EXCEPTION_XML_NODE_UNKNOWN);
171                 }
172
173                 // Call method
174                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
175                 call_user_func_array(array($this, $methodName), $attributes);
176         }
177
178         /**
179          * Ends the main or sub node by sending out the gathered data
180          *
181          * @param       $resource       An XML resource pointer (currently ignored)
182          * @param       $nodeName       Name of the node we want to finish
183          * @return      void
184          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
185          */
186         public function endElement ($resource, $nodeName) {
187                 // Make all lower-case
188                 $nodeName = strtolower($nodeName);
189
190                 // Does this match with current main node?
191                 //* DEBUG: */ echo "END: &gt;".$nodeName."&lt;<br />\n";
192                 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
193                         // Did not match!
194                         throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), XmlParser::EXCEPTION_XML_NODE_MISMATCH);
195                 } elseif (in_array($nodeName, $this->getSubNodes())) {
196                         // Silently ignore sub nodes
197                         return;
198                 }
199
200                 // Construct method name
201                 $methodName = 'finish' . $this->convertToClassName($nodeName);
202
203                 // Call the corresponding method
204                 call_user_func_array(array($this->getImageInstance(), $methodName), array());
205         }
206
207         /**
208          * Currently not used
209          *
210          * @param       $resource               XML parser resource (currently ignored)
211          * @param       $characters             Characters to handle
212          * @return      void
213          * @todo        Find something usefull with this!
214          */
215         public function characterHandler ($resource, $characters) {
216                 // Trim all spaces away
217                 $characters = trim($characters);
218
219                 // Is this string empty?
220                 if (empty($characters)) {
221                         // Then skip it silently
222                         return false;
223                 } // END - if
224
225                 // Unfinished work!
226                 $this->partialStub("Handling extra characters is not yet supported!");
227         }
228
229         /**
230          * Intializes the image
231          *
232          * @return      void
233          * @todo        Add cache creation here
234          */
235         private function initImage () {
236                 // Unfinished work!
237         }
238
239         /**
240          * Set the image type
241          *
242          * @param       $imageType      Code fragment or direct value holding the image type
243          * @return      void
244          */
245         private function setImageType ($imageType) {
246                 // Set group to general
247                 $this->setVariableGroup('general');
248
249                 // Try to compile it first to get the value from variable stack
250                 $imageType = $this->compileRawCode($imageType);
251
252                 // Now make a class name of it
253                 $className = $this->convertToClassName($imageType.'_image');
254
255                 // And try to initiate it
256                 $this->setImageInstance(ObjectFactory::createObjectByName($className, array($this)));
257
258                 // Set current main node to type
259                 $this->currMainNode = 'type';
260         }
261
262         /**
263          * "Setter" for resolution, we first need to collect the resolution from the
264          * sub-nodes. So first, this method will prepare an array for it
265          *
266          * @return      void
267          */
268         private function setImageResolution () {
269                 // Call the image class
270                 $this->getImageInstance()->initResolution();
271
272                 // Current main node is resolution
273                 $this->currMainNode = 'resolution';
274         }
275
276         /**
277          * "Setter" for base information. For more details see above method!
278          *
279          * @return      void
280          * @see         ImageTemplateEngine::setImageResolution
281          */
282         private function setImageBase () {
283                 // Call the image class
284                 $this->getImageInstance()->initBase();
285
286                 // Current main node is resolution
287                 $this->currMainNode = 'base';
288         }
289
290         /**
291          * "Setter" for background-color. For more details see above method!
292          *
293          * @return      void
294          * @see         ImageTemplateEngine::setImageResolution
295          */
296         private function setImageBackgroundColor () {
297                 // Call the image class
298                 $this->getImageInstance()->initBackgroundColor();
299
300                 // Current main node is background-color
301                 $this->currMainNode = 'background-color';
302         }
303
304         /**
305          * "Setter" for foreground-color. For more details see above method!
306          *
307          * @return      void
308          * @see         ImageTemplateEngine::setImageResolution
309          */
310         private function setImageForegroundColor () {
311                 // Call the image class
312                 $this->getImageInstance()->initForegroundColor();
313
314                 // Current main node is foreground-color
315                 $this->currMainNode = 'foreground-color';
316         }
317
318         /**
319          * "Setter" for image-string. For more details see above method!
320          *
321          * @param       $groupable      Wether this image string is groupable
322          * @return      void
323          * @see         ImageTemplateEngine::setImageResolution
324          */
325         private function setImageImageString ($groupable = 'single') {
326                 // Call the image class
327                 $this->getImageInstance()->initImageString($groupable);
328
329                 // Current main node is foreground-color
330                 $this->currMainNode = 'image-string';
331         }
332
333         /**
334          * Setter for image name
335          *
336          * @param       $imageName      Name of the image
337          * @return      void
338          */
339         private function setImagePropertyName ($imageName) {
340                 // Call the image class
341                 $this->getImageInstance()->setImageName($imageName);
342         }
343
344         /**
345          * Setter for image width
346          *
347          * @param       $width  Width of the image or variable
348          * @return      void
349          */
350         private function setImagePropertyWidth ($width) {
351                 // Call the image class
352                 $this->getImageInstance()->setWidth($width);
353         }
354
355         /**
356          * Setter for image height
357          *
358          * @param       $height Height of the image or variable
359          * @return      void
360          */
361         private function setImagePropertyHeight ($height) {
362                 // Call the image class
363                 $this->getImageInstance()->setHeight($height);
364         }
365
366         /**
367          * Setter for image red color
368          *
369          * @param       $red    Red color value
370          * @return      void
371          */
372         private function setImagePropertyRed ($red) {
373                 // Call the image class
374                 $this->getImageInstance()->setRed($red);
375         }
376
377         /**
378          * Setter for image green color
379          *
380          * @param       $green  Green color value
381          * @return      void
382          */
383         private function setImagePropertyGreen ($green) {
384                 // Call the image class
385                 $this->getImageInstance()->setGreen($green);
386         }
387
388         /**
389          * Setter for image blue color
390          *
391          * @param       $blue   Blue color value
392          * @return      void
393          */
394         private function setImagePropertyBlue ($blue) {
395                 // Call the image class
396                 $this->getImageInstance()->setBlue($blue);
397         }
398
399         /**
400          * Setter for string name (identifier)
401          *
402          * @param       $stringName             String name (identifier)
403          * @return      void
404          */
405         private function setImagePropertyStringName ($stringName) {
406                 // Call the image class
407                 $this->getImageInstance()->setStringName($stringName);
408         }
409
410         /**
411          * Setter for font size
412          *
413          * @param       $fontSize       Size of the font
414          * @return      void
415          */
416         private function setImagePropertyFontSize ($fontSize) {
417                 // Call the image class
418                 $this->getImageInstance()->setFontSize($fontSize);
419         }
420
421         /**
422          * Setter for image string
423          *
424          * @param       $imageString    Image string to set
425          * @return      void
426          */
427         private function setImagePropertyText ($imageString) {
428                 // Call the image class
429                 $this->getImageInstance()->setString($imageString);
430         }
431
432         /**
433          * Setter for X coordinate
434          *
435          * @param       $x      X coordinate
436          * @return      void
437          */
438         private function setImagePropertyX ($x) {
439                 // Call the image class
440                 $this->getImageInstance()->setX($x);
441         }
442
443         /**
444          * Setter for Y coordinate
445          *
446          * @param       $y      Y coordinate
447          * @return      void
448          */
449         private function setImagePropertyY ($y) {
450                 // Call the image class
451                 $this->getImageInstance()->setY($y);
452         }
453
454         /**
455          * Getter for image cache file (FQFN)
456          *
457          * @return      $fqfn   Full-qualified file name of the image cache
458          */
459         public function getImageCacheFqfn () {
460                 // Get the FQFN ready
461                 $fqfn = sprintf("%s%s%s/%s.%s",
462                         $this->getConfigInstance()->getConfigEntry('base_path'),
463                         $this->getGenericBasePath(),
464                         'images/_cache',
465                         md5(
466                                 $this->getImageInstance()->getImageName() . ':' . $this->__toString() . ':' . $this->getImageInstance()->__toString()
467                         ),
468                         $this->getImageInstance()->getImageType()
469                 );
470
471                 // Return it
472                 return $fqfn;
473         }
474
475         /**
476          * Outputs the image to the world
477          *
478          * @param       $responseInstance       An instance of a Responseable class
479          * @return      void
480          */
481         public function transferToResponse (Responseable $responseInstance) {
482                 // Set the image instance
483                 $responseInstance->setImageInstance($this->getImageInstance());
484         }
485
486         /**
487          * Load a specified image template into the engine
488          *
489          * @param       $template       The image template we shall load which is
490          *                                              located in 'image' by default
491          * @return      void
492          */
493         public function loadImageTemplate ($template) {
494                 // Set template type
495                 $this->setTemplateType($this->getConfigInstance()->getConfigEntry('image_template_type'));
496
497                 // Load the special template
498                 $this->loadTemplate($template);
499         }
500 }
501
502 // [EOF]
503 ?>