inc/classes/main/helper/web/class_HtmlFormHelper.php

   1 <?php
   2 /**
   3  * A helper for constructing HTML forms
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright(c) 2007, 2008 Roland Haeder, this is free software
   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 HtmlFormHelper extends BaseTemplateHelper {
  25         /**
  26          * Wether the form tag is opened (keep at false or else your forms will
  27          * never work!)
  28          */
  29         private $formOpened = false;
  30
  31         /**
  32          * Name of the form
  33          */
  34         private $formName = "";
  35
  36         /**
  37          * Wether the group is opened or not
  38          */
  39         private $groupOpened = false;
  40
  41         /**
  42          * Wether the sub group is opened or not
  43          */
  44         private $subGroupOpened = false;
  45
  46         // Class Constants
  47         const EXCEPTION_FORM_NAME_INVALID = 0xb00;
  48         const EXCEPTION_CLOSED_FORM       = 0xb01;
  49         const EXCEPTION_OPENED_FORM       = 0xb02;
  50
  51         /**
  52          * Private constructor
  53          *
  54          * @return      void
  55          */
  56         protected function __construct () {
  57                 // Call parent constructor
  58                 parent::__construct(__CLASS__);
  59
  60                 // Set part description
  61                 $this->setObjectDescription("HTML-Formularhilfsklasse");
  62         }
  63
  64         /**
  65          * Creates the helper class with the given template engine instance and form name
  66          *
  67          * @param       $templateInstance       An instance of a valid template engine
  68          * @param       $formName                       Name of the form
  69          * @param       $formId                         Value for "id" attribute (default: $formName)
  70          * @return      $helperInstance         A preparedf instance of this class
  71          */
  72         public final static function createHtmlFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) {
  73                 // Get new instance
  74                 $helperInstance = new HtmlFormHelper();
  75
  76                 // Set template instance
  77                 $helperInstance->setTemplateInstance($templateInstance);
  78
  79                 // Is the form id not set?
  80                 if ($formId === false) {
  81                         // Use form id from form name
  82                         $formId = $formName;
  83                 }
  84
  85                 // Create the form
  86                 $helperInstance->addFormTag($formName, $formId);
  87
  88                 // Return the prepared instance
  89                 return $helperInstance;
  90         }
  91
  92         /**
  93          * Add the form tag or close it an already opened form tag
  94          *
  95          * @param       $formName       Name of the form (default: false)
  96          * @param       $formId         Id of the form (attribute "id"; default: false)
  97          * @return      void
  98          * @throws      InvalidFormNameException        If the form name is invalid (=false)
  99          */
 100         public function addFormTag ($formName = false, $formId = false) {
 101                 // When the form is not yet opened at least form name must be valid
 102                 if ((!$this->formOpened) && ($formName === false)) {
 103                         // Thrown an exception
 104                         throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
 105                 }
 106
 107                 // Close the form is default
 108                 $formContent = "</form>";
 109
 110                 // Check wether we shall open or close the form
 111                 if (!$this->formOpened) {
 112                         // Add HTML code
 113                         $formContent = sprintf("<form name=\"%s\" action=\"%s\" method=\"%s\" target=\"%s\"",
 114                                 $formName,
 115                                 $this->getConfigInstance()->readConfig("form_action"),
 116                                 $this->getConfigInstance()->readConfig("form_method"),
 117                                 $this->getConfigInstance()->readConfig("form_target")
 118                         );
 119
 120                         // Is the form id set?
 121                         if ($formId !== false) {
 122                                 // Then add it as well
 123                                 $formContent .= sprintf(" id=\"%s\"",
 124                                         $formId
 125                                 );
 126                         }
 127
 128                         // Add close bracket
 129                         $formContent .= ">";
 130
 131                         // Open the form and remeber the form name
 132                         $this->formOpened = true;
 133                         $this->formName = $formName;
 134                 } else {
 135                         // Add the hidden field required to identify safely this form
 136                         $this->addInputHiddenField("form", $this->formName);
 137
 138                         // @TODO Add some unique PIN here to bypass problems with some browser and/or extensions
 139                         // Simply close it
 140                         $this->formOpened = false;
 141                 }
 142
 143                 // Add it to the content
 144                 $this->addContent($formContent);
 145         }
 146
 147         /**
 148          * Add an input tag to the form or throw an exception if it is not yet
 149          * opened. The field's name will be set as id.
 150          *
 151          * @param       $fieldName                      Input field name
 152          * @param       $fieldSize                      Input size
 153          * @param       $fieldMaxLength         Input max length
 154          * @param       $fieldValue                     Input default value (default: empty)
 155          * @return      void
 156          * @throws      FormClosedException             If the form is not yet opened
 157          */
 158         public function addInputTextField ($fieldName, $fieldSize, $fieldMaxLength, $fieldValue = "") {
 159                 // Is the form opened?
 160                 if (!$this->formOpened) {
 161                         // Throw an exception
 162                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 163                 }
 164
 165                 // Generate the content
 166                 $inputContent = sprintf("<input type=\"text\" id=\"%s\" name=\"%s\" size=\"%d\" maxlength=\"%d\" value=\"%s\" />",
 167                         $fieldName, $fieldName, $fieldSize, $fieldMaxLength, $fieldValue);
 168
 169                 // And add it
 170                 $this->addContent($inputContent);
 171         }
 172
 173         /**
 174          * Flushs the content out (not yet secured against open forms, etc.!) or
 175          * throw an exception if it is not yet closed
 176          *
 177          * @return      void
 178          * @throws      FormOpenedException             If the form is still open
 179          */
 180         public function flushContent () {
 181                 // Is the form opened?
 182                 if ($this->formOpened) {
 183                         // Throw an exception
 184                         throw new FormOpenedException ($this, self::EXCEPTION_OPENED_FORM);
 185                 }
 186
 187                 // Send content to template engine
 188                 $this->getTemplateInstance()->assignVariable($this->formName, $this->getContent());
 189         }
 190
 191         /**
 192          * Add a form group or close an already opened and open a new one
 193          *
 194          * @param       $groupName      Name of the group
 195          * @param       $groupText      Text including HTML to show above this group
 196          * @return      void
 197          * @throws      EmptyVariableException  If $groupName is not set
 198          */
 199         public function addFormGroup ($groupName, $groupText) {
 200                 // At least the group name should be set
 201                 if (empty($groupName)) {
 202                         // Throw exception here
 203                         throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 204                 }
 205
 206                 // Not fully finished!
 207                 $this->partialStub(__METHOD__);
 208
 209                 // Is this group opened?
 210                 if (!$this->groupOpened) {
 211                         // Switch the state
 212                         $this->groupOpened = true;
 213                 } else {
 214                         // Switch the state
 215                         $this->groupOpened = false;
 216
 217                         // All call it again
 218                         $this->addFormGroup($groupName, $groupText);
 219                 }
 220         }
 221 }
 222
 223 // [EOF]
 224 ?>