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

   1 <?php
   2 /**
   3  * A helper for constructing web 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 WebFormHelper extends BaseHelper {
  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         /**
  47          * Name of the sub group
  48          */
  49         private $subGroupName = "";
  50
  51         // Class Constants
  52         const EXCEPTION_FORM_NAME_INVALID       = 0xb00;
  53         const EXCEPTION_CLOSED_FORM             = 0xb01;
  54         const EXCEPTION_OPENED_FORM             = 0xb02;
  55         const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0xb03;
  56
  57         /**
  58          * Private constructor
  59          *
  60          * @return      void
  61          */
  62         protected function __construct () {
  63                 // Call parent constructor
  64                 parent::__construct(__CLASS__);
  65
  66                 // Set part description
  67                 $this->setObjectDescription("Helper class for HTML forms");
  68
  69                 // Create unique ID number
  70                 $this->createUniqueID();
  71         }
  72
  73         /**
  74          * Creates the helper class with the given template engine instance and form name
  75          *
  76          * @param       $templateInstance       An instance of a valid template engine
  77          * @param       $formName                       Name of the form
  78          * @param       $formId                         Value for "id" attribute (default: $formName)
  79          * @return      $helperInstance         A preparedf instance of this class
  80          */
  81         public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) {
  82                 // Get new instance
  83                 $helperInstance = new WebFormHelper();
  84
  85                 // Set template instance
  86                 $helperInstance->setTemplateInstance($templateInstance);
  87
  88                 // Is the form id not set?
  89                 if ($formId === false) {
  90                         // Use form id from form name
  91                         $formId = $formName;
  92                 }
  93
  94                 // Create the form
  95                 $helperInstance->addFormTag($formName, $formId);
  96
  97                 // Return the prepared instance
  98                 return $helperInstance;
  99         }
 100
 101         /**
 102          * Add the form tag or close it an already opened form tag
 103          *
 104          * @param       $formName       Name of the form (default: false)
 105          * @param       $formId         Id of the form (attribute "id"; default: false)
 106          * @return      void
 107          * @throws      InvalidFormNameException        If the form name is invalid (=false)
 108          */
 109         public function addFormTag ($formName = false, $formId = false) {
 110                 // When the form is not yet opened at least form name must be valid
 111                 if (($this->formOpened === false) && ($formName === false)) {
 112                         // Thrown an exception
 113                         throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
 114                 }
 115
 116                 // Close the form is default
 117                 $formContent = "</form>";
 118
 119                 // Check wether we shall open or close the form
 120                 if ($this->formOpened === false) {
 121                         // Add HTML code
 122                         $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s\" method=\"%s\" target=\"%s\"",
 123                                 $formName,
 124                                 $this->getConfigInstance()->readConfig('form_action'),
 125                                 $this->getConfigInstance()->readConfig('form_method'),
 126                                 $this->getConfigInstance()->readConfig('form_target')
 127                         );
 128
 129                         // Is the form id set?
 130                         if ($formId !== false) {
 131                                 // Then add it as well
 132                                 $formContent .= sprintf(" id=\"%s_form\"",
 133                                         $formId
 134                                 );
 135                         }
 136
 137                         // Add close bracket
 138                         $formContent .= ">";
 139
 140                         // Open the form and remeber the form name
 141                         $this->formOpened = true;
 142                         $this->formName = $formName;
 143                 } else {
 144                         // Add the hidden field required to identify safely this form
 145                         $this->addInputHiddenField('form', $this->formName);
 146
 147                         // Is a group open?
 148                         if ($this->groupOpened === true) {
 149                                 // Then automatically close it here
 150                                 $this->addFormGroup("", "");
 151                         }
 152
 153                         // @TODO Add some unique PIN here to bypass problems with some browser and/or extensions
 154                         // Simply close it
 155                         $this->formOpened = false;
 156                 }
 157
 158                 // Add it to the content
 159                 $this->addContent($formContent);
 160         }
 161
 162         /**
 163          * Add a text input tag to the form or throw an exception if it is not yet
 164          * opened. The field's name will be set as id.
 165          *
 166          * @param       $fieldName                      Input field name
 167          * @param       $fieldValue                     Input default value (default: empty)
 168          * @return      void
 169          * @throws      FormClosedException             If the form is not yet opened
 170          */
 171         public function addInputTextField ($fieldName, $fieldValue = "") {
 172                 // Is the form opened?
 173                 if ($this->formOpened === false) {
 174                         // Throw an exception
 175                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 176                 }
 177
 178                 // Generate the content
 179                 $inputContent = sprintf("<input type=\"text\" class=\"textfield\" id=\"%s\" name=\"%s\" value=\"%s\" />",
 180                         $fieldName,
 181                         $fieldName,
 182                         $fieldValue
 183                 );
 184
 185                 // And add it maybe with a "li" tag
 186                 $this->addContent($inputContent);
 187         }
 188
 189         /**
 190          * Add a password input tag to the form or throw an exception if it is not
 191          * yet opened. The field's name will be set as id.
 192          *
 193          * @param       $fieldName                      Input field name
 194          * @param       $fieldValue                     Input default value (default: empty)
 195          * @return      void
 196          * @throws      FormClosedException             If the form is not yet opened
 197          */
 198         public function addInputPasswordField ($fieldName, $fieldValue = "") {
 199                 // Is the form opened?
 200                 if ($this->formOpened === false) {
 201                         // Throw an exception
 202                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 203                 }
 204
 205                 // Generate the content
 206                 $inputContent = sprintf("<input type=\"password\" class=\"password\" id=\"%s\" name=\"%s\" value=\"%s\" />",
 207                         $fieldName,
 208                         $fieldName,
 209                         $fieldValue
 210                 );
 211
 212                 // And add it
 213                 $this->addContent($inputContent);
 214         }
 215
 216         /**
 217          * Add a hidden input tag to the form or throw an exception if it is not
 218          * yet opened. The field's name will be set as id.
 219          *
 220          * @param       $fieldName                      Input field name
 221          * @param       $fieldValue                     Input default value (default: empty)
 222          * @return      void
 223          * @throws      FormClosedException             If the form is not yet opened
 224          */
 225         public function addInputHiddenField ($fieldName, $fieldValue = "") {
 226                 // Is the form opened?
 227                 if ($this->formOpened === false) {
 228                         // Throw an exception
 229                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 230                 }
 231
 232                 // Generate the content
 233                 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
 234                         $fieldName,
 235                         $fieldValue
 236                 );
 237
 238                 // And add it
 239                 $this->addContent($inputContent);
 240         }
 241
 242         /**
 243          * Add a checkbox input tag to the form or throw an exception if it is not
 244          * yet opened. The field's name will be set as id.
 245          *
 246          * @param       $fieldName                      Input field name
 247          * @param       $fieldChecked           Wether the field is checked (defaut: checked)
 248          * @return      void
 249          * @throws      FormClosedException             If the form is not yet opened
 250          */
 251         public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
 252                 // Is the form opened?
 253                 if ($this->formOpened === false) {
 254                         // Throw an exception
 255                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 256                 }
 257
 258                 // Set wether the check box is checked...
 259                 $checked = " checked=\"checked\"";
 260                 if ($fieldChecked === false) $checked = " ";
 261
 262                 // Generate the content
 263                 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox\" id=\"%s\" value=\"1\"%s/>",
 264                         $fieldName,
 265                         $fieldName,
 266                         $checked
 267                 );
 268
 269                 // And add it
 270                 $this->addContent($inputContent);
 271         }
 272
 273         /**
 274          * Add a reset input tag to the form or throw an exception if it is not
 275          * yet opened. The field's name will be set as id.
 276          *
 277          * @param       $buttonText             Text displayed on the button
 278          * @return      void
 279          * @throws      FormClosedException             If the form is not yet opened
 280          */
 281         public function addInputResetButton ($buttonText) {
 282                 // Is the form opened?
 283                 if ($this->formOpened === false) {
 284                         // Throw an exception
 285                         throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
 286                 }
 287
 288                 // Generate the content
 289                 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
 290                         $this->formName,
 291                         $buttonText
 292                 );
 293
 294                 // And add it
 295                 $this->addContent($inputContent);
 296         }
 297
 298         /**
 299          * Add a reset input tag to the form or throw an exception if it is not
 300          * yet opened. The field's name will be set as id.
 301          *
 302          * @param       $buttonText                     Text displayed on the button
 303          * @return      void
 304          * @throws      FormClosedException             If the form is not yet opened
 305          */
 306         public function addInputSubmitButton ($buttonText) {
 307                 // Is the form opened?
 308                 if ($this->formOpened === false) {
 309                         // Throw an exception
 310                         throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
 311                 }
 312
 313                 // Generate the content
 314                 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
 315                         $this->formName,
 316                         $this->formName,
 317                         $buttonText
 318                 );
 319
 320                 // And add it
 321                 $this->addContent($inputContent);
 322         }
 323
 324         /**
 325          * Add a form group or close an already opened and open a new one
 326          *
 327          * @param       $groupName      Name of the group
 328          * @param       $groupText      Text including HTML to show above this group
 329          * @return      void
 330          * @throws      FormClosedException             If no form has been opened before
 331          * @throws      EmptyVariableException  If $groupName is not set
 332          */
 333         public function addFormGroup ($groupName, $groupText) {
 334                 // Is a form opened?
 335                 if ($this->formOpened === false) {
 336                         // Throw exception here
 337                         throw new FormClosedException(array($this, $groupName), self::EXCEPTION_CLOSED_FORM);
 338                 }
 339
 340                 // At least the group name should be set
 341                 if ((empty($groupName)) && ($this->groupOpened === false)) {
 342                         // Throw exception here
 343                         throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 344                 }
 345
 346                 // Initialize content with closing div by default
 347                 $content = "    </div>\n</div><!-- Group - CLOSE //-->";
 348
 349                 // Is this group opened?
 350                 if ($this->groupOpened === false) {
 351                         // Begin the div/span blocks
 352                         $content = sprintf("<!-- Group %s - OPEN //-->
 353 <div class=\"group_box\" id=\"%s_group_box\">
 354         <span class=\"group_text\" id=\"%s_group_text\">
 355                 %s
 356         </span>
 357         <div class=\"group_field\" id=\"%s_group_field\">",
 358                                 $groupName,
 359                                 $groupName,
 360                                 $groupName,
 361                                 $groupText,
 362                                 $groupName
 363                         );
 364
 365                         // Add the content
 366                         $this->addContent($content);
 367
 368                         // Switch the state
 369                         $this->groupOpened = true;
 370                 } else {
 371                         // Is a sub group opened?
 372                         if ($this->subGroupOpened === true) {
 373                                 // Close it here
 374                                 $this->addFormSubGroup("", "");
 375                         }
 376
 377                         // Add the content
 378                         $this->addContent($content);
 379
 380                         // Switch the state
 381                         $this->groupOpened = false;
 382
 383                         // All call it again if the group name is not empty
 384                         if (!empty($groupName)) {
 385                                 $this->addFormGroup($groupName, $groupText);
 386                         }
 387                 }
 388         }
 389
 390         /**
 391          * Add a form sub group or close an already opened and open a new one or
 392          * throws an exception if no group has been opened before or if the sub
 393          * group name is empty.
 394          *
 395          * @param       $subGroupName   Name of the group
 396          * @param       $subGroupText   Text including HTML to show above this group
 397          * @return      void
 398          * @throws      FormGroupClosedException        If no group has been opened before
 399          * @throws      EmptyVariableException          If $subGroupName is not set
 400          */
 401         public function addFormSubGroup ($subGroupName, $subGroupText) {
 402                 // Is a group opened?
 403                 if ($this->groupOpened === false) {
 404                         // Throw exception here
 405                         throw new FormGroupClosedException(array($this, $subGroupName), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
 406                 }
 407
 408                 // At least the sub group name should be set
 409                 if ((empty($subGroupName)) && ($this->subGroupOpened === false)) {
 410                         // Throw exception here
 411                         throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 412                 }
 413
 414                 // Initialize content with closing div by default
 415                 $content = "    </div>\n</div><!-- Sub group- CLOSE //-->";
 416
 417                 // Is this group opened?
 418                 if ($this->subGroupOpened === false) {
 419                         // Begin the span block
 420                         $content = sprintf("<!-- Sub group %s - OPEN //-->
 421 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
 422         <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
 423                 %s
 424         </span>
 425         <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
 426                                 $subGroupName,
 427                                 $subGroupName,
 428                                 $subGroupName,
 429                                 $subGroupText,
 430                                 $subGroupName
 431                         );
 432
 433                         // Add the content
 434                         $this->addContent($content);
 435
 436                         // Switch the state and remeber the name
 437                         $this->subGroupOpened = true;
 438                         $this->subGroupName = $subGroupName;
 439                 } else {
 440                         // Add the content
 441                         $this->addContent($content);
 442
 443                         // Switch the state
 444                         $this->subGroupOpened = false;
 445
 446                         // All call it again if sub group name is not empty
 447                         if (!empty($subGroupName)) {
 448                                 $this->addFormSubGroup($subGroupName, $subGroupText);
 449                         }
 450                 }
 451         }
 452
 453         /**
 454          * Add text surrounded by a span block when there is a group opened before
 455          * or else by a div block.
 456          *
 457          * @param       $fieldName                      Field name
 458          * @param       $fieldText                      Text for the field
 459          * @return      void
 460          * @throws      FormClosedException             If the form is not yet opened
 461          */
 462         public function addFieldText ($fieldName, $fieldText) {
 463                 // Is the form opened?
 464                 if ($this->formOpened === false) {
 465                         // Throw an exception
 466                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 467                 }
 468
 469                 // Set the block type
 470                 $block = "div";
 471                 if ($this->groupOpened === true) $block = "span";
 472
 473                 // Generate the content
 474                 $inputContent = sprintf("       <%s id=\"%s_text\">
 475                 %s
 476         </%s>",
 477                         $block,
 478                         $fieldName,
 479                         $fieldText,
 480                         $block
 481                 );
 482
 483                 // And add it
 484                 $this->addContent($inputContent);
 485         }
 486
 487         /**
 488          * Add text (notes) surrounded by a div block. Still opened groups or sub
 489          * groups will be automatically closed.
 490          *
 491          * @param       $formNotes      The form notes we shell addd
 492          * @return      void
 493          * @throws      FormClosedException             If the form is not yet opened
 494          */
 495         public function addFormNote ($formNotes) {
 496                 // Is the form opened?
 497                 if ($this->formOpened === false) {
 498                         // Throw an exception
 499                         throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
 500                 }
 501
 502                 // Is a group open?
 503                 if ($this->groupOpened === true) {
 504                         // Then automatically close it here
 505                         $this->addFormGroup("unknown", "");
 506                 }
 507
 508                 // Generate the content
 509                 $inputContent = sprintf("       <div id=\"form_note\">
 510                 %s
 511         </div>",
 512                         $formNotes
 513                 );
 514
 515                 // And add it
 516                 $this->addContent($inputContent);
 517         }
 518
 519         /**
 520          * Checks wether the registration requires a valid email address
 521          *
 522          * @return      $required       Wether the email address is required
 523          */
 524         public function ifRegisterRequiresEmailVerification () {
 525                 $required = ($this->getConfigInstance()->readConfig('register_requires_email') == "Y");
 526                 return $required;
 527         }
 528
 529         /**
 530          * Checks wether profile data shall be asked
 531          *
 532          * @return      $required       Wether profile shall be asked
 533          */
 534         public function ifRegisterIncludesProfile () {
 535                 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') == "Y");
 536                 return $required;
 537         }
 538
 539         /**
 540          * Checks wether personal data shall be asked
 541          *
 542          * @return      $required       Wether personal data shall be asked
 543          */
 544         public function ifRegisterIncludesPersonaData () {
 545                 $required = ($this->getConfigInstance()->readConfig('register_personal_data') == "Y");
 546                 return $required;
 547         }
 548
 549         /**
 550          * Checks wether email addresses can only be once used
 551          *
 552          * @return      $isUnique
 553          */
 554         public function ifEmailMustBeUnique () {
 555                 $isUnique = ($this->getConfigInstance()->readConfig('register_email_unique') == "Y");
 556                 return $isUnique;
 557         }
 558
 559         /**
 560          * Checks wether the specified chat protocol is enabled in this form
 561          *
 562          * @return      $required       Wether the specified chat protocol is enabled
 563          */
 564         public function ifChatEnabled ($chatProtocol) {
 565                 $required = ($this->getConfigInstance()->readConfig(sprintf("chat_enabled_%s", $chatProtocol)) == "Y");
 566                 return $required;
 567         }
 568
 569         /**
 570          * Flushs the content out (not yet secured against open forms, etc.!) or
 571          * throw an exception if it is not yet closed
 572          *
 573          * @return      void
 574          * @throws      FormOpenedException             If the form is still open
 575          */
 576         public function flushContent () {
 577                 // Is the form still open?
 578                 if ($this->formOpened === true) {
 579                         // Throw an exception
 580                         throw new FormOpenedException ($this, self::EXCEPTION_OPENED_FORM);
 581                 }
 582
 583                 // Send content to template engine
 584                 $this->getTemplateInstance()->assignVariable($this->formName, $this->getContent());
 585         }
 586 }
 587
 588 // [EOF]
 589 ?>