inc/classes/main/template/mail/class_MailTemplateEngine.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  * @todo                This template engine does not make use of setTemplateType()
  11  *
  12  * This program is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation, either version 3 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  24  */
  25 class MailTemplateEngine extends BaseTemplateEngine implements CompileableTemplate {
  26         /**
  27          * Main nodes in the XML tree
  28          */
  29         private $mainNodes = array(
  30                 'mail-data'
  31         );
  32
  33         /**
  34          * Sub nodes in the XML tree
  35          */
  36         private $subNodes = array(
  37                 'subject-line',
  38                 'sender-address',
  39                 'recipient-address',
  40                 'message'
  41         );
  42
  43         /**
  44          * Mailer instance
  45          */
  46         private $mailerInstance = null;
  47
  48         /**
  49          * Current main node
  50          */
  51         private $currMainNode = '';
  52
  53         /**
  54          * Protected constructor
  55          *
  56          * @return      void
  57          */
  58         protected function __construct () {
  59                 // Call parent constructor
  60                 parent::__construct(__CLASS__);
  61         }
  62
  63         /**
  64          * Creates an instance of the class TemplateEngine and prepares it for usage
  65          *
  66          * @param       $appInstance    A manageable application
  67          * @return      $templateInstance       An instance of TemplateEngine
  68          * @throws      BasePathIsEmptyException                If the provided $templateBasePath is empty
  69          * @throws      InvalidBasePathStringException  If $templateBasePath is no string
  70          * @throws      BasePathIsNoDirectoryException  If $templateBasePath is no
  71          *                                                                                      directory or not found
  72          * @throws      BasePathReadProtectedException  If $templateBasePath is
  73          *                                                                                      read-protected
  74          */
  75         public static final function createMailTemplateEngine (ManageableApplication $appInstance) {
  76                 // Get a new instance
  77                 $templateInstance = new MailTemplateEngine();
  78
  79                 // Determine base path
  80                 $templateBasePath = $templateInstance->getConfigInstance()->getConfigEntry('application_base_path') . $appInstance->getRequestInstance()->getRequestElement('app') . '/';
  81
  82                 // Is the base path valid?
  83                 if (empty($templateBasePath)) {
  84                         // Base path is empty
  85                         throw new BasePathIsEmptyException($templateInstance, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
  86                 } elseif (!is_string($templateBasePath)) {
  87                         // Is not a string
  88                         throw new InvalidBasePathStringException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_STRING);
  89                 } elseif (!is_dir($templateBasePath)) {
  90                         // Is not a path
  91                         throw new BasePathIsNoDirectoryException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_PATH_NAME);
  92                 } elseif (!is_readable($templateBasePath)) {
  93                         // Is not readable
  94                         throw new BasePathReadProtectedException(array($templateInstance, $templateBasePath), self::EXCEPTION_READ_PROTECED_PATH);
  95                 }
  96
  97                 // Set the base path
  98                 $templateInstance->setTemplateBasePath($templateBasePath);
  99
 100                 // Set template extensions
 101                 $templateInstance->setRawTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('raw_template_extension'));
 102                 $templateInstance->setCodeTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('code_template_extension'));
 103
 104                 // Absolute output path for compiled templates
 105                 $templateInstance->setCompileOutputPath($templateInstance->getConfigInstance()->getConfigEntry('base_path') . $templateInstance->getConfigInstance()->getConfigEntry('compile_output_path'));
 106
 107                 // Return the prepared instance
 108                 return $templateInstance;
 109         }
 110
 111         /**
 112          * Getter for current main node
 113          *
 114          * @return      $currMainNode   Current main node
 115          */
 116         public final function getCurrMainNode () {
 117                 return $this->currMainNode;
 118         }
 119
 120         /**
 121          * Getter for main node array
 122          *
 123          * @return      $mainNodes      Array with valid main node names
 124          */
 125         public final function getMainNodes () {
 126                 return $this->mainNodes;
 127         }
 128
 129         /**
 130          * Getter for sub node array
 131          *
 132          * @return      $subNodes       Array with valid sub node names
 133          */
 134         public final function getSubNodes () {
 135                 return $this->subNodes;
 136         }
 137
 138         /**
 139          * Handles the start element of an XML resource
 140          *
 141          * @param       $resource               XML parser resource (currently ignored)
 142          * @param       $element                The element we shall handle
 143          * @param       $attributes             All attributes
 144          * @return      void
 145          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
 146          */
 147         protected function startElement ($resource, $element, array $attributes) {
 148                 // Initial method name which will never be called...
 149                 $methodName = 'initEmail';
 150
 151                 // Make the element name lower-case
 152                 $element = strtolower($element);
 153
 154                 // Is the element a main node?
 155                 //* DEBUG: */ echo "START: &gt;".$element."&lt;<br />\n";
 156                 if (in_array($element, $this->getMainNodes())) {
 157                         // Okay, main node found!
 158                         $methodName = 'setEmail' . $this->convertToClassName($element);
 159                 } elseif (in_array($element, $this->getSubNodes())) {
 160                         // Sub node found
 161                         $methodName = 'setEmailProperty' . $this->convertToClassName($element);
 162                 } elseif ($element != 'text-mail') {
 163                         // Invalid node name found
 164                         throw new InvalidXmlNodeException(array($this, $element, $attributes), XmlParser::EXCEPTION_XML_NODE_UNKNOWN);
 165                 }
 166
 167                 // Call method
 168                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 169                 call_user_func_array(array($this, $methodName), $attributes);
 170         }
 171
 172         /**
 173          * Ends the main or sub node by sending out the gathered data
 174          *
 175          * @param       $resource       An XML resource pointer (currently ignored)
 176          * @param       $nodeName       Name of the node we want to finish
 177          * @return      void
 178          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
 179          */
 180         protected function endElement ($resource, $nodeName) {
 181                 // Make all lower-case
 182                 $nodeName = strtolower($nodeName);
 183
 184                 // Does this match with current main node?
 185                 //* DEBUG: */ echo "END: &gt;".$nodeName."&lt;<br />\n";
 186                 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
 187                         // Did not match!
 188                         throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), XmlParser::EXCEPTION_XML_NODE_MISMATCH);
 189                 } elseif (in_array($nodeName, $this->getSubNodes())) {
 190                         // Silently ignore sub nodes
 191                         return;
 192                 }
 193
 194                 // Construct method name
 195                 $methodName = 'finish' . $this->convertToClassName($nodeName);
 196
 197                 // Call the corresponding method
 198                 call_user_func_array(array($this, $methodName), array());
 199         }
 200
 201         /**
 202          * Adds the message text to the template engine
 203          *
 204          * @param       $resource               XML parser resource (currently ignored)
 205          * @param       $characters             Characters to handle
 206          * @return      void
 207          */
 208         protected function characterHandler ($resource, $characters) {
 209                 // Trim all spaces away
 210                 $characters = trim($characters);
 211
 212                 // Is this string empty?
 213                 if (empty($characters)) {
 214                         // Then skip it silently
 215                         return false;
 216                 } // END - if
 217
 218                 // Add the message now
 219                 $this->assignVariable('message', $characters);
 220         }
 221
 222         /**
 223          * Intializes the mail
 224          *
 225          * @return      void
 226          * @todo        Add cache creation here
 227          */
 228         private function initEmail () {
 229                 // Unfinished work!
 230         }
 231
 232         /**
 233          * Setter for mail data node
 234          *
 235          * @return      void
 236          * @todo        Should we call back the mailer class here?
 237          */
 238         private function setEmailMailData () {
 239                 // Set current main node
 240                 $this->currMainNode = 'mail-data';
 241         }
 242
 243         /**
 244          * Setter for sender address property
 245          *
 246          * @param       $senderAddress  Sender address to set in email
 247          * @return      void
 248          */
 249         private function setEmailPropertySenderAddress ($senderAddress) {
 250                 // Set the template variable
 251                 $this->assignVariable('sender', $senderAddress);
 252         }
 253
 254         /**
 255          * Setter for recipient address property
 256          *
 257          * @param       $recipientAddress       Recipient address to set in email
 258          * @return      void
 259          */
 260         private function setEmailPropertyRecipientAddress ($recipientAddress) {
 261                 // Set the template variable
 262                 $this->assignVariable('recipient', $recipientAddress);
 263         }
 264
 265         /**
 266          * Setter for subject line property
 267          *
 268          * @param       $subjectLine    Subject line to set in email
 269          * @return      void
 270          */
 271         private function setEmailPropertySubjectLine ($subjectLine) {
 272                 // Set the template variable
 273                 $this->assignVariable('subject', $subjectLine);
 274         }
 275
 276         /**
 277          * Method stub to avoid output
 278          *
 279          * @return      void
 280          */
 281         private function setEmailPropertyMessage () {
 282                 // Empty for now
 283         }
 284
 285         /**
 286          * Gets the template variable "message", stores it back as raw template data
 287          * and compiles all variables so the mail message got prepared for output
 288          *
 289          * @return      void
 290          */
 291         private function finishMailData () {
 292                 // Get the message and set it as new raw template data back
 293                 $message = $this->readVariable('message');
 294                 $this->setRawTemplateData($message);
 295
 296                 // Get some variables to compile
 297                 //$sender = $this->compileRawCode($this->readVariable('sender'));
 298                 //$this->assignVariable('sender', $sender);
 299
 300                 // Then compile all variables
 301                 $this->compileVariables();
 302         }
 303
 304         /**
 305          * Invokes the final mail process
 306          *
 307          * @return      void
 308          */
 309         private function finishTextMail () {
 310                 $this->getMailerInstance()->invokeMailDelivery();
 311         }
 312
 313         /**
 314          * Getter for image cache file (FQFN)
 315          *
 316          * @return      $fqfn   Full-qualified file name of the image cache
 317          * @todo        0% done
 318          */
 319         public function getMailCacheFqfn () {
 320                 // Initialize FQFN
 321                 $fqfn = '';
 322                 $this->debugBackTrace();
 323
 324                 // Return it
 325                 return $fqfn;
 326         }
 327
 328         /**
 329          * Setter for mailer instance
 330          *
 331          * @param       $mailerInstance         A mailer instance
 332          * @return      void
 333          */
 334         public final function setMailerInstance (DeliverableMail $mailerInstance) {
 335                 $this->mailerInstance = $mailerInstance;
 336         }
 337
 338         /**
 339          * Getter for mailer instance
 340          *
 341          * @return      $mailerInstance         A mailer instance
 342          */
 343         protected final function getMailerInstance () {
 344                 return $this->mailerInstance;
 345         }
 346
 347         /**
 348          * Outputs the mail to the world. This should only the mailer debug class do!
 349          *
 350          * @param       $responseInstance       An instance of a Responseable class
 351          * @return      void
 352          */
 353         public function transferToResponse (Responseable $responseInstance) {
 354                 $responseInstance->writeToBody($this->getCompiledData());
 355         }
 356 }
 357
 358 // [EOF]
 359 ?>