3 namespace Org\Mxchange\CoreFramework\Template\Engine;
5 // Import framework stuff
6 use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap;
7 use Org\Mxchange\CoreFramework\Factory\ObjectFactory;
8 use Org\Mxchange\CoreFramework\Filesystem\InvalidDirectoryException;
9 use Org\Mxchange\CoreFramework\Image\BaseImage;
10 use Org\Mxchange\CoreFramework\Parser\Parseable;
11 use Org\Mxchange\CoreFramework\Registry\GenericRegistry;
12 use Org\Mxchange\CoreFramework\Response\Responseable;
13 use Org\Mxchange\CoreFramework\Template\CompileableTemplate;
14 use Org\Mxchange\CoreFramework\Template\Engine\BaseTemplateEngine;
15 use Org\Mxchange\CoreFramework\Utils\String\StringUtils;
19 use \UnexpectedValueException;
22 * The own template engine for loading caching and sending out images
24 * @author Roland Haeder <webmaster@shipsimu.org>
26 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2020 Core Developer Team
27 * @license GNU GPL 3.0 or any newer version
28 * @link http://www.shipsimu.org
30 * This program is free software: you can redistribute it and/or modify
31 * it under the terms of the GNU General Public License as published by
32 * the Free Software Foundation, either version 3 of the License, or
33 * (at your option) any later version.
35 * This program is distributed in the hope that it will be useful,
36 * but WITHOUT ANY WARRANTY; without even the implied warranty of
37 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
38 * GNU General Public License for more details.
40 * You should have received a copy of the GNU General Public License
41 * along with this program. If not, see <http://www.gnu.org/licenses/>.
43 class ImageTemplateEngine extends BaseTemplateEngine implements CompileableTemplate {
45 * Main nodes in the XML tree ('image' is ignored)
47 private $mainNodes = array(
57 * Sub nodes in the XML tree
59 private $subNodes = array(
76 private $currMainNode = '';
79 * Instance of the image
81 private $imageInstance = NULL;
84 * Protected constructor
88 protected function __construct () {
89 // Call parent constructor
90 parent::__construct(__CLASS__);
94 * Creates an instance of the class TemplateEngine and prepares it for usage
96 * @return $templateInstance An instance of TemplateEngine
97 * @throws UnexpectedValueException If the provided $templateBasePath is empty or no string
98 * @throws InvalidDirectoryException If $templateBasePath is no
99 * directory or not found
100 * @throws BasePathReadProtectedException If $templateBasePath is
103 public static final function createImageTemplateEngine () {
104 // Get a new instance
105 $templateInstance = new ImageTemplateEngine();
107 // Get the application instance from registry
108 $applicationInstance = GenericRegistry::getRegistry()->getInstance('application');
110 // Determine base path
111 $templateBasePath = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('application_base_path') . $applicationInstance->getAppShortName(). '/';
113 // Is the base path valid?
114 if (empty($templateBasePath)) {
115 // Base path is empty
116 throw new UnexpectedValueException(sprintf('[%s:%d] Variable templateBasePath is empty.', $templateInstance->__toString(), __LINE__), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
117 } elseif (!is_string($templateBasePath)) {
119 throw new UnexpectedValueException(sprintf('[%s:%d] %s is not a string with a base path.', $templateInstance->__toString(), __LINE__, $templateBasePath), self::EXCEPTION_INVALID_STRING);
120 } elseif (!is_dir($templateBasePath)) {
122 throw new InvalidDirectoryException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_PATH_NAME);
123 } elseif (!is_readable($templateBasePath)) {
125 throw new BasePathReadProtectedException(array($templateInstance, $templateBasePath), self::EXCEPTION_READ_PROTECED_PATH);
129 $templateInstance->setTemplateBasePath($templateBasePath);
131 // Set template extensions
132 $templateInstance->setRawTemplateExtension(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('raw_template_extension'));
133 $templateInstance->setCodeTemplateExtension(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('code_template_extension'));
135 // Absolute output path for compiled templates
136 $templateInstance->setCompileOutputPath(sprintf('%s%s/',
138 FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('compile_output_path')
141 // Return the prepared instance
142 return $templateInstance;
146 * Getter for current main node
148 * @return $currMainNode Current main node
150 public final function getCurrMainNode () {
151 return $this->currMainNode;
155 * Getter for main node array
157 * @return $mainNodes Array with valid main node names
159 public final function getMainNodes () {
160 return $this->mainNodes;
164 * Getter for sub node array
166 * @return $subNodes Array with valid sub node names
168 public final function getSubNodes () {
169 return $this->subNodes;
173 * Setter for image instance
175 * @param $imageInstance An instance of an image
178 public final function setImageInstance (BaseImage $imageInstance) {
179 $this->imageInstance = $imageInstance;
183 * Getter for image instance
185 * @return $imageInstance An instance of an image
187 public final function getImageInstance () {
188 return $this->imageInstance;
192 * Handles the start element of an XML resource
194 * @param $resource XML parser resource (currently ignored)
195 * @param $element The element we shall handle
196 * @param $attributes All attributes
198 * @throws InvalidXmlNodeException If an unknown/invalid XML node name was found
200 public function startElement ($resource, $element, array $attributes) {
201 // Initial method name which will never be called...
202 $methodName = 'initImage';
204 // Make the element name lower-case
205 $element = strtolower($element);
207 // Is the element a main node?
208 //* DEBUG: */ echo "START: >".$element."<<br />\n";
209 if (in_array($element, $this->mainNodes)) {
210 // Okay, main node found!
211 $methodName = 'setImage' . StringUtils::convertToClassName($element);
212 } elseif (in_array($element, $this->subNodes)) {
214 $methodName = 'setImageProperty' . StringUtils::convertToClassName($element);
215 } elseif ($element != 'image') {
216 // Invalid node name found
217 throw new InvalidXmlNodeException(array($this, $element, $attributes), Parseable::EXCEPTION_XML_NODE_UNKNOWN);
221 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
222 call_user_func_array(array($this, $methodName), $attributes);
226 * Ends the main or sub node by sending out the gathered data
228 * @param $resource An XML resource pointer (currently ignored)
229 * @param $nodeName Name of the node we want to finish
231 * @throws XmlNodeMismatchException If current main node mismatches the closing one
233 public function finishElement ($resource, $nodeName) {
234 // Make all lower-case
235 $nodeName = strtolower($nodeName);
237 // Does this match with current main node?
238 //* DEBUG: */ echo "END: >".$nodeName."<<br />\n";
239 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
241 throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), Parseable::EXCEPTION_XML_NODE_MISMATCH);
242 } elseif (in_array($nodeName, $this->getSubNodes())) {
243 // Silently ignore sub nodes
247 // Construct method name
248 $methodName = sprintf('finish%s', StringUtils::convertToClassName($nodeName));
250 // Call the corresponding method
251 call_user_func_array(array($this->getImageInstance(), $methodName), []);
257 * @param $resource XML parser resource (currently ignored)
258 * @param $characters Characters to handle
260 * @todo Find something usefull with this!
262 public function characterHandler ($resource, $characters) {
263 // Trim all spaces away
264 $characters = trim($characters);
266 // Is this string empty?
267 if (empty($characters)) {
268 // Then skip it silently
273 $this->partialStub('Handling extra characters is not yet supported!');
277 * Intializes the image
280 * @todo Add cache creation here
282 private function initImage () {
289 * @param $imageType Code fragment or direct value holding the image type
292 private function setImageType ($imageType) {
293 // Set group to general
294 $this->setVariableGroup('general');
296 // Try to compile it first to get the value from variable stack
297 $imageType = $this->compileRawCode($imageType);
299 // Now make a class name of it
300 $className = StringUtils::convertToClassName($imageType.'_image');
302 // And try to initiate it
303 $this->setImageInstance(ObjectFactory::createObjectByName($className, array($this)));
305 // Set current main node to type
306 $this->currMainNode = 'type';
310 * "Setter" for resolution, we first need to collect the resolution from the
311 * sub-nodes. So first, this method will prepare an array for it
315 private function setImageResolution () {
316 // Call the image class
317 $this->getImageInstance()->initResolution();
319 // Current main node is resolution
320 $this->currMainNode = 'resolution';
324 * "Setter" for base information. For more details see above method!
327 * @see ImageTemplateEngine::setImageResolution
329 private function setImageBase () {
330 // Call the image class
331 $this->getImageInstance()->initBase();
333 // Current main node is resolution
334 $this->currMainNode = 'base';
338 * "Setter" for background-color. For more details see above method!
341 * @see ImageTemplateEngine::setImageResolution
343 private function setImageBackgroundColor () {
344 // Call the image class
345 $this->getImageInstance()->initBackgroundColor();
347 // Current main node is background-color
348 $this->currMainNode = 'background-color';
352 * "Setter" for foreground-color. For more details see above method!
355 * @see ImageTemplateEngine::setImageResolution
357 private function setImageForegroundColor () {
358 // Call the image class
359 $this->getImageInstance()->initForegroundColor();
361 // Current main node is foreground-color
362 $this->currMainNode = 'foreground-color';
366 * "Setter" for image-string. For more details see above method!
368 * @param $groupable Whether this image string is groupable
370 * @see ImageTemplateEngine::setImageResolution
372 private function setImageImageString ($groupable = 'single') {
373 // Call the image class
374 $this->getImageInstance()->initImageString($groupable);
376 // Current main node is foreground-color
377 $this->currMainNode = 'image-string';
381 * Setter for image name
383 * @param $imageName Name of the image
386 private function setImagePropertyName ($imageName) {
387 // Call the image class
388 $this->getImageInstance()->setImageName($imageName);
392 * Setter for image width
394 * @param $width Width of the image or variable
397 private function setImagePropertyWidth ($width) {
398 // Call the image class
399 $this->getImageInstance()->setWidth($width);
403 * Setter for image height
405 * @param $height Height of the image or variable
408 private function setImagePropertyHeight ($height) {
409 // Call the image class
410 $this->getImageInstance()->setHeight($height);
414 * Setter for image red color
416 * @param $red Red color value
419 private function setImagePropertyRed ($red) {
420 // Call the image class
421 $this->getImageInstance()->setRed($red);
425 * Setter for image green color
427 * @param $green Green color value
430 private function setImagePropertyGreen ($green) {
431 // Call the image class
432 $this->getImageInstance()->setGreen($green);
436 * Setter for image blue color
438 * @param $blue Blue color value
441 private function setImagePropertyBlue ($blue) {
442 // Call the image class
443 $this->getImageInstance()->setBlue($blue);
447 * Setter for string name (identifier)
449 * @param $stringName String name (identifier)
452 private function setImagePropertyStringName ($stringName) {
453 // Call the image class
454 $this->getImageInstance()->setStringName($stringName);
458 * Setter for font size
460 * @param $fontSize Size of the font
463 private function setImagePropertyFontSize ($fontSize) {
464 // Call the image class
465 $this->getImageInstance()->setFontSize($fontSize);
469 * Setter for image string
471 * @param $imageString Image string to set
474 private function setImagePropertyText ($imageString) {
475 // Call the image class
476 $this->getImageInstance()->setString($imageString);
480 * Setter for X coordinate
482 * @param $x X coordinate
485 private function setImagePropertyX ($x) {
486 // Call the image class
487 $this->getImageInstance()->setX($x);
491 * Setter for Y coordinate
493 * @param $y Y coordinate
496 private function setImagePropertyY ($y) {
497 // Call the image class
498 $this->getImageInstance()->setY($y);
502 * Getter for image cache file instance
504 * @return $fileInstance An instance of a SplFileInfo class
506 public function getImageCacheFile () {
507 // Get the instance ready
508 $fileInstance = new SplFileInfo(sprintf('%s%s%s/%s.%s',
509 FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('root_base_path'),
510 $this->getGenericBasePath(),
513 $this->getImageInstance()->getImageName() . ':' . $this->__toString() . ':' . $this->getImageInstance()->__toString()
515 $this->getImageInstance()->getImageType()
519 return $fileInstance;
523 * Outputs the image to the world
525 * @param $responseInstance An instance of a Responseable class
527 * @todo Nothing to really "transfer" here?
529 public function transferToResponse (Responseable $responseInstance) {
530 // Set the image instance
531 $responseInstance->setImageInstance($this->getImageInstance());
535 * Load a specified image template into the engine
537 * @param $template The image template we shall load which is
538 * located in 'image' by default
541 public function loadImageTemplate ($template) {
543 $this->setTemplateType(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('image_template_type'));
545 // Load the special template
546 $this->loadTemplate($template);