framework/main/classes/decorator/xml/template/class_XmlRewriterTemplateDecorator.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Template\Xml;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Generic\BaseDecorator;
   7 use Org\Mxchange\CoreFramework\Response\Responseable;
   8 use Org\Mxchange\CoreFramework\Template\Xml\CompileableXmlTemplate;
   9 use Org\Mxchange\CoreFramework\Traits\Template\CompileableTemplateTrait;
  10
  11 /**
  12  * A decorator for XML template engines which rewrites the XML for compacting
  13  * it.
  14  *
  15  * @author              Roland Haeder <webmaster@shipsimu.org>
  16  * @version             0.0.0
  17  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  18  * @license             GNU GPL 3.0 or any newer version
  19  * @link                http://www.shipsimu.org
  20  *
  21  * This program is free software: you can redistribute it and/or modify
  22  * it under the terms of the GNU General Public License as published by
  23  * the Free Software Foundation, either version 3 of the License, or
  24  * (at your option) any later version.
  25  *
  26  * This program is distributed in the hope that it will be useful,
  27  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  28  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  29  * GNU General Public License for more details.
  30  *
  31  * You should have received a copy of the GNU General Public License
  32  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  33  */
  34 class XmlRewriterTemplateDecorator extends BaseDecorator implements CompileableXmlTemplate {
  35         // Load traits
  36         use CompileableTemplateTrait;
  37
  38         /**
  39          * Protected constructor
  40          *
  41          * @return      void
  42          */
  43         private function __construct () {
  44                 // Call parent constructor
  45                 parent::__construct(__CLASS__);
  46         }
  47
  48         /**
  49          * Creates an instance of the class TemplateEngine and prepares it for usage
  50          *
  51          * @param       $innerTemplateInstance  A CompileableXmlTemplate instance
  52          * @return      $templateInstance       An instance of TemplateEngine
  53          */
  54         public static final function createXmlRewriterTemplateDecorator (CompileableXmlTemplate $innerTemplateInstance) {
  55                 // Get a new instance
  56                 $templateInstance = new XmlRewriterTemplateDecorator();
  57
  58                 // Set the inner template engine
  59                 $templateInstance->setTemplateInstance($innerTemplateInstance);
  60
  61                 // Return the prepared instance
  62                 return $templateInstance;
  63         }
  64
  65         /**
  66          * Settter for variable group
  67          *
  68          * @param       $groupName      Name of variable group
  69          * @param       $add            Whether add this group
  70          * @return      void
  71          */
  72         public function setVariableGroup (string $groupName, bool $add = true) {
  73                 // Call the inner class' method
  74                 $this->getTemplateInstance()->setVariableGroup($groupName, $add);
  75         }
  76
  77         /**
  78          * Adds a variable to current group
  79          *
  80          * @param       $variableName   Variable to set
  81          * @param       $value  Value to store in variable
  82          * @return      void
  83          */
  84         public function addGroupVariable (string $variableName, $value) {
  85                 // Call the inner class' method
  86                 $this->getTemplateInstance()->addGroupVariable($variableName, $value);
  87         }
  88
  89         /**
  90          * Getter for base path
  91          *
  92          * @return      $templateBasePath       The relative base path for all templates
  93          */
  94         public final function getTemplateBasePath () {
  95                 // Call the inner class' method
  96                 return $this->getTemplateInstance()->getTemplateBasePath();
  97         }
  98
  99         /**
 100          * Getter for generic base path
 101          *
 102          * @return      $templateBasePath       The relative base path for all templates
 103          */
 104         public final function getGenericBasePath () {
 105                 // Call the inner class' method
 106                 return $this->getTemplateInstance()->getGenericBasePath();
 107         }
 108
 109         /**
 110          * Getter for template extension
 111          *
 112          * @return      $templateExtension      The file extension for all uncompiled templates
 113          */
 114         public final function getRawTemplateExtension () {
 115                 // Call the inner class' method
 116                 return $this->getTemplateInstance()->getRawTemplateExtension();
 117         }
 118
 119         /**
 120          * Getter for given variable group
 121          *
 122          * @param       $variableGroup  Variable group to check
 123          * @return      $varStack               Found variable group
 124          */
 125         public function getVarStack (string $variableGroup) {
 126                 // Call the inner class' method
 127                 return $this->getTemplateInstance()->getVarStack($variableGroup);
 128         }
 129
 130         /**
 131          * Getter for code-template extension
 132          *
 133          * @return      $codeExtension  The file extension for all code templates
 134          */
 135         public final function getCodeTemplateExtension () {
 136                 // Call the inner class' method
 137                 return $this->getTemplateInstance()->getCodeTemplateExtension();
 138         }
 139
 140         /**
 141          * Getter for template type
 142          *
 143          * @return      $templateType   The current template's type
 144          */
 145         public final function getTemplateType () {
 146                 // Call the inner class' method
 147                 return $this->getTemplateInstance()->getTemplateType();
 148         }
 149
 150         /**
 151          * Assign (add) a given variable with a value
 152          *
 153          * @param       $variableName   The variable we are looking for
 154          * @param       $value  The value we want to store in the variable
 155          * @return      void
 156          */
 157         public function assignVariable (string $variableName, $value) {
 158                 // Call the inner class' method
 159                 $this->getTemplateInstance()->assignVariable($variableName, $value);
 160         }
 161
 162         /**
 163          * Removes a given variable
 164          *
 165          * @param       $variableName   The variable we are looking for
 166          * @param       $variableGroup  Name of variable group (default: 'general')
 167          * @return      void
 168          */
 169         public function removeVariable (string $variableName, string $variableGroup = 'general') {
 170                 // Call the inner class' method
 171                 $this->getTemplateInstance()->removeVariable($variableName, $variableGroup);
 172         }
 173
 174         /**
 175          * Load a specified HTML template into the engine
 176          *
 177          * @param       $template       The web template we shall load which is located in
 178          *                                              'html' by default
 179          * @return      void
 180          */
 181         public function loadHtmlTemplate (string $template) {
 182                 // Call the inner class' method
 183                 $this->getTemplateInstance()->loadHtmlTemplate($template);
 184         }
 185
 186         /**
 187          * Assign a given congfiguration variable with a value
 188          *
 189          * @param       $variableName   The configuration variable we want to assign
 190          * @return      void
 191          */
 192         public function assignConfigVariable (string $variableName) {
 193                 // Call the inner class' method
 194                 $this->getTemplateInstance()->assignConfigVariable($variableName);
 195         }
 196
 197         /**
 198          * Load a specified code template into the engine
 199          *
 200          * @param       $template       The code template we shall load which is
 201          *                                              located in 'code' by default
 202          * @return      void
 203          */
 204         public function loadCodeTemplate (string $template) {
 205                 // Call the inner class' method
 206                 $this->getTemplateInstance()->loadCodeTemplate($template);
 207         }
 208
 209         /**
 210          * Load a specified email template into the engine for later compilation
 211          * with other code/web/email templates.
 212          *
 213          * @param       $template       The email template we shall load which is
 214          *                                              located in "html" by default
 215          * @return      void
 216          */
 217         public function loadEmailTemplate ($template) {
 218                 // Call the inner class' method
 219                 $this->getTemplateInstance()->loadEmailTemplate($template);
 220         }
 221
 222         /**
 223          * Compiles configuration place-holders in all variables. This 'walks'
 224          * through the variable stack 'general'. It interprets all values from that
 225          * variables as configuration entries after compiling them.
 226          *
 227          * @return      void
 228          */
 229         public function compileConfigInVariables () {
 230                 // Call the inner class' method
 231                 $this->getTemplateInstance()->compileConfigInVariables();
 232         }
 233
 234         /**
 235          * Compile all variables by inserting their respective values
 236          *
 237          * @return      void
 238          */
 239         public function compileVariables () {
 240                 // Call the inner class' method
 241                 $this->getTemplateInstance()->compileVariables();
 242         }
 243
 244         /**
 245          * Compile all required templates into the current loaded one
 246          *
 247          * @return      void
 248          */
 249         public function compileTemplate () {
 250                 // Call the inner class' method
 251                 $this->getTemplateInstance()->compileTemplate();
 252         }
 253
 254         /**
 255          * Assigns the last loaded raw template content with a given variable
 256          *
 257          * @param       $templateName   Name of the template we want to assign
 258          * @param       $variableName   Name of the variable we want to assign
 259          * @return      void
 260          */
 261         public function assignTemplateWithVariable (string $templateName, string $variableName) {
 262                 // Call the inner class' method
 263                 $this->getTemplateInstance()->assignTemplateWithVariable($templateName, $variableName);
 264         }
 265
 266         /**
 267          * Transfers the content of this template engine to a given response instance
 268          *
 269          * @param       $responseInstance       An instance of a Responseable class
 270          * @return      void
 271          */
 272         public function transferToResponse (Responseable $responseInstance) {
 273                 // Call the inner class' method
 274                 $this->getTemplateInstance()->transportToResponse($responseInstance);
 275         }
 276
 277         /**
 278          * Assigns all the application data with template variables
 279          *
 280          * @return      void
 281          */
 282         public function assignApplicationData () {
 283                 // Call the inner class' method
 284                 $this->getTemplateInstance()->assignApplicationData();
 285         }
 286
 287         /**
 288          * "Compiles" a variable by replacing {?var?} with it's content
 289          *
 290          * @param       $rawCode                        Raw code to compile
 291          * @param       $setMatchAsCode         Sets $match if readVariable() returns empty result
 292          * @return      $rawCode                        Compile code with inserted variable value
 293          */
 294         public function compileRawCode (string $rawCode, bool $setMatchAsCode = false) {
 295                 return $this->getTemplateInstance()->compileRawCode($rawCode, $setMatchAsCode);
 296         }
 297
 298         /**
 299          * Getter for variable group array
 300          *
 301          * @return      $variableGroups         All variable groups
 302          */
 303         public final function getVariableGroups () {
 304                 // Call the inner class' method
 305                 return $this->getTemplateInstance()->getVariableGroups();
 306         }
 307
 308         /**
 309          * Getter for raw template data
 310          *
 311          * @return      $rawTemplateData        The raw data from the template
 312          */
 313         public function getRawTemplateData () {
 314                 // Call the inner class' method
 315                 return $this->getTemplateInstance()->getRawTemplateData();
 316         }
 317
 318         /**
 319          * Renames a variable in code and in stack
 320          *
 321          * @param       $oldName        Old name of variable
 322          * @param       $newName        New name of variable
 323          * @return      void
 324          */
 325         public function renameVariable (string $oldName, string $newName) {
 326                 // Call the inner class' method
 327                 $this->getTemplateInstance()->renameVariable($oldName, $newName);
 328         }
 329
 330         /**
 331          * Renders the given XML content
 332          *
 333          * @param       $content        Valid XML content or if not set the current loaded raw content
 334          * @return      void
 335          * @throws      XmlParserException      If an XML error was found
 336          */
 337         public function renderXmlContent (string $content = NULL) {
 338                 // Call the inner class' method
 339                 $this->getTemplateInstance()->renderXmlContent($content);
 340         }
 341
 342         /**
 343          * Enables or disables language support
 344          *
 345          * @param       $languageSupport        New language support setting
 346          * @return      void
 347          */
 348         public function enableLanguageSupport (bool $languageSupport = true) {
 349                 // Call the inner class' method
 350                 $this->getTemplateInstance()->enableLanguageSupport($languageSupport);
 351         }
 352
 353         /**
 354          * Checks whether language support is enabled
 355          *
 356          * @return      $languageSupport        Whether language support is enabled or disabled
 357          */
 358         public function isLanguageSupportEnabled () {
 359                 // Call the inner class' method
 360                 return $this->getTemplateInstance()->isLanguageSupportEnabled();
 361         }
 362
 363         /**
 364          * Enables or disables XML compacting
 365          *
 366          * @param       $xmlCompacting  New XML compacting setting
 367          * @return      void
 368          */
 369         public function enableXmlCompacting (bool $xmlCompacting = true) {
 370                 // Call the inner class' method
 371                 $this->getTemplateInstance()->enableXmlCompacting($xmlCompacting);
 372         }
 373
 374         /**
 375          * Checks whether XML compacting is enabled
 376          *
 377          * @return      $xmlCompacting  Whether XML compacting is enabled or disabled
 378          */
 379         public function isXmlCompactingEnabled () {
 380                 // Call the inner class' method
 381                 return $this->getTemplateInstance()->isXmlCompactingEnabled();
 382         }
 383
 384         /**
 385          * Handles the start element of an XML resource
 386          *
 387          * @param       $resource               XML parser resource (currently ignored)
 388          * @param       $element                The element we shall handle
 389          * @param       $attributes             All attributes
 390          * @return      void
 391          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
 392          */
 393         public function startElement ($resource, string $element, array $attributes) {
 394                 // Call the inner class' method
 395                 $this->getTemplateInstance()->startElement($resource, $element, $attributes);
 396         }
 397
 398         /**
 399          * Ends the main or sub node by sending out the gathered data
 400          *
 401          * @param       $resource       An XML resource pointer (currently ignored)
 402          * @param       $nodeName       Name of the node we want to finish
 403          * @return      void
 404          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
 405          */
 406         public function finishElement ($resource, string $nodeName) {
 407                 // Call the inner class' method
 408                 $this->getTemplateInstance()->finishElement($resource, $nodeName);
 409         }
 410
 411         /**
 412          * Currently not used
 413          *
 414          * @param       $resource               XML parser resource (currently ignored)
 415          * @param       $characters             Characters to handle
 416          * @return      void
 417          * @todo        Find something useful with this!
 418          */
 419         public function characterHandler ($resource, string $characters) {
 420                 // Call the inner class' method but trim the characters before
 421                 $this->getTemplateInstance()->characterHandler($resource, trim($characters));
 422         }
 423
 424         /**
 425          * Removes all comments, tabs and new-line charcters to compact the content
 426          *
 427          * @param       $uncompactedContent             The uncompacted content
 428          * @return      $compactedContent               The compacted content
 429          */
 430         public function compactContent (string $uncompactedContent) {
 431                 // Compact it ...
 432                 $compactedContent = $this->getTemplateInstance()->compactContent($uncompactedContent);
 433
 434                 // ... and return it
 435                 return $compactedContent;
 436         }
 437
 438         /**
 439          * Assigns a lot variables into the stack of currently loaded template.
 440          * This method should only be used in very rare circumstances, e.g. when
 441          * you have to copy a whole set of variables into the template engine.
 442          * Before you use this method, please make sure you have considered all
 443          * other possiblities.
 444          *
 445          * @param       $variables      An array with variables to be assigned
 446          * @return      void
 447          */
 448         public function assignMultipleVariables (array $variables) {
 449                 // Call the inner class' method but trim the characters before
 450                 $this->getTemplateInstance()->assignMultipleVariables($variables);
 451         }
 452
 453 }