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