inc/classes/main/helper/web/forms/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 BaseWebHelper implements HelpableTemplate {
  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 form tag is enabled (default: true)
  38          */
  39         private $formEnabled = true;
  40
  41         // Class Constants
  42         const EXCEPTION_FORM_NAME_INVALID       = 0x120;
  43         const EXCEPTION_CLOSED_FORM             = 0x121;
  44         const EXCEPTION_OPENED_FORM             = 0x122;
  45         const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x123;
  46
  47         /**
  48          * Protected constructor
  49          *
  50          * @return      void
  51          */
  52         protected function __construct () {
  53                 // Call parent constructor
  54                 parent::__construct(__CLASS__);
  55         }
  56
  57         /**
  58          * Creates the helper class with the given template engine instance and form name
  59          *
  60          * @param       $templateInstance       An instance of a valid template engine
  61          * @param       $formName                       Name of the form
  62          * @param       $formId                         Value for "id" attribute (default: $formName)
  63          * @param       $withForm                       Wether include the form tag
  64          * @return      $helperInstance         A preparedf instance of this helper
  65          */
  66         public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false, $withForm = true) {
  67                 // Get new instance
  68                 $helperInstance = new WebFormHelper();
  69
  70                 // Set template instance
  71                 $helperInstance->setTemplateInstance($templateInstance);
  72
  73                 // Is the form id not set?
  74                 if ($formId === false) {
  75                         // Use form id from form name
  76                         $formId = $formName;
  77                 } // END - if
  78
  79                 // Set form name
  80                 $helperInstance->setFormName($formName);
  81
  82                 // A form-less field may say "false" here...
  83                 if ($withForm === true) {
  84                         // Create the form
  85                         $helperInstance->addFormTag($formName, $formId);
  86                 } else {
  87                         // Disable form
  88                         $helperInstance->enableForm(false);
  89                 }
  90
  91                 // Return the prepared instance
  92                 return $helperInstance;
  93         }
  94
  95         /**
  96          * Add the form tag or close it an already opened form tag
  97          *
  98          * @param       $formName       Name of the form (default: false)
  99          * @param       $formId         Id of the form (attribute "id"; default: false)
 100          * @return      void
 101          * @throws      InvalidFormNameException        If the form name is invalid (=false)
 102          * @todo        Add some unique PIN here to bypass problems with some browser and/or extensions
 103          */
 104         public function addFormTag ($formName = false, $formId = false) {
 105                 // When the form is not yet opened at least form name must be valid
 106                 if (($this->formOpened === false) && ($formName === false)) {
 107                         // Thrown an exception
 108                         throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
 109                 } // END - if
 110
 111                 // Close the form is default
 112                 $formContent = "</form>";
 113
 114                 // Check wether we shall open or close the form
 115                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 116                         // Add HTML code
 117                         $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
 118                                 $formName,
 119                                 $this->getConfigInstance()->readConfig('base_url'),
 120                                 $this->getConfigInstance()->readConfig('form_action'),
 121                                 $this->getConfigInstance()->readConfig('form_method'),
 122                                 $this->getConfigInstance()->readConfig('form_target')
 123                         );
 124
 125                         // Add form id as well
 126                         $formContent .= sprintf(" id=\"%s_form\"",
 127                                 $formId
 128                         );
 129
 130                         // Add close bracket
 131                         $formContent .= ">";
 132
 133                         // Open the form and remeber the form name
 134                         $this->formOpened = true;
 135
 136                         // Add it to the content
 137                         $this->addHeaderContent($formContent);
 138                 } else {
 139                         // Add the hidden field required to identify safely this form
 140                         $this->addInputHiddenField('form', $this->getFormName());
 141
 142                         // Is a group open?
 143                         if ($this->ifGroupOpenedPreviously()) {
 144                                 // Then automatically close it here
 145                                 $this->addFormGroup();
 146                         } // END - if
 147
 148                         // Simply close it
 149                         $this->formOpened = false;
 150
 151                         // Add it to the content
 152                         $this->addFooterContent($formContent);
 153                 }
 154         }
 155
 156         /**
 157          * Add a text input tag to the form or throw an exception if it is not yet
 158          * opened. The field's name will be set as id.
 159          *
 160          * @param       $fieldName              Input field name
 161          * @param       $fieldValue             Input default value (default: empty)
 162          * @return      void
 163          * @throws      FormClosedException             If the form is not yet opened
 164          */
 165         public function addInputTextField ($fieldName, $fieldValue = "") {
 166                 // Is the form opened?
 167                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 168                         // Throw an exception
 169                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 170                 } // END - if
 171
 172                 // Generate the content
 173                 $inputContent = sprintf("<input type=\"text\" class=\"textfield %s_field\" name=\"%s\" value=\"%s\" />",
 174                         $fieldName,
 175                         $fieldName,
 176                         $fieldValue
 177                 );
 178
 179                 // And add it maybe with a "li" tag
 180                 $this->addContentToPreviousGroup($inputContent);
 181         }
 182
 183         /**
 184          * Add a text input tag to the form with pre-loaded default value
 185          *
 186          * @param       $fieldName      Input field name
 187          * @return      void
 188          */
 189         public function addInputTextFieldWithDefault ($fieldName) {
 190                 // Get the value from instance
 191                 $fieldValue = $this->getValueField($fieldName);
 192                 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
 193
 194                 // Add the text field
 195                 $this->addInputTextField($fieldName, $fieldValue);
 196         }
 197
 198         /**
 199          * Add a password input tag to the form or throw an exception if it is not
 200          * yet opened. The field's name will be set as id.
 201          *
 202          * @param       $fieldName              Input field name
 203          * @param       $fieldValue             Input default value (default: empty)
 204          * @return      void
 205          * @throws      FormClosedException             If the form is not yet opened
 206          */
 207         public function addInputPasswordField ($fieldName, $fieldValue = "") {
 208                 // Is the form opened?
 209                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 210                         // Throw an exception
 211                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 212                 } // END - if
 213
 214                 // Generate the content
 215                 $inputContent = sprintf("<input type=\"password\" class=\"password %s_field\" name=\"%s\" value=\"%s\" />",
 216                         $fieldName,
 217                         $fieldName,
 218                         $fieldValue
 219                 );
 220
 221                 // And add it
 222                 $this->addContentToPreviousGroup($inputContent);
 223         }
 224
 225         /**
 226          * Add a hidden input tag to the form or throw an exception if it is not
 227          * yet opened. The field's name will be set as id.
 228          *
 229          * @param       $fieldName              Input field name
 230          * @param       $fieldValue             Input default value (default: empty)
 231          * @return      void
 232          * @throws      FormClosedException             If the form is not yet opened
 233          */
 234         public function addInputHiddenField ($fieldName, $fieldValue = "") {
 235                 // Is the form opened?
 236                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 237                         // Throw an exception
 238                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 239                 } // END - if
 240
 241                 // Generate the content
 242                 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
 243                         $fieldName,
 244                         $fieldValue
 245                 );
 246
 247                 // And add it
 248                 $this->addContentToPreviousGroup($inputContent);
 249         }
 250
 251         /**
 252          * Add a hidden input tag to the form with pre-loaded default value
 253          *
 254          * @param       $fieldName      Input field name
 255          * @return      void
 256          */
 257         public function addInputHiddenFieldWithDefault ($fieldName) {
 258                 // Get the value from instance
 259                 $fieldValue = $this->getValueField($fieldName);
 260                 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
 261
 262                 // Add the text field
 263                 $this->addInputHiddenField($fieldName, $fieldValue);
 264         }
 265
 266         /**
 267          * Add a hidden input tag to the form with configuration value
 268          *
 269          * @param       $fieldName      Input field name
 270          * @param       $prefix         Prefix for configuration without trailing _
 271          * @return      void
 272          */
 273         public function addInputHiddenConfiguredField ($fieldName, $prefix) {
 274                 // Get the value from instance
 275                 $fieldValue = $this->getConfigInstance()->readConfig("{$prefix}_{$fieldName}");
 276                 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
 277
 278                 // Add the text field
 279                 $this->addInputHiddenField($fieldName, $fieldValue);
 280         }
 281
 282         /**
 283          * Add a checkbox input tag to the form or throw an exception if it is not
 284          * yet opened. The field's name will be set as id.
 285          *
 286          * @param       $fieldName              Input field name
 287          * @param       $fieldChecked   Wether the field is checked (defaut: checked)
 288          * @return      void
 289          * @throws      FormClosedException             If the form is not yet opened
 290          */
 291         public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
 292                 // Is the form opened?
 293                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 294                         // Throw an exception
 295                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 296                 } // END - if
 297
 298                 // Set wether the check box is checked...
 299                 $checked = " checked=\"checked\"";
 300                 if ($fieldChecked === false) $checked = " ";
 301
 302                 // Generate the content
 303                 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox %s_field\" value=\"1\"%s/>",
 304                         $fieldName,
 305                         $fieldName,
 306                         $checked
 307                 );
 308
 309                 // And add it
 310                 $this->addContentToPreviousGroup($inputContent);
 311         }
 312
 313         /**
 314          * Add a reset input tag to the form or throw an exception if it is not
 315          * yet opened. The field's name will be set as id.
 316          *
 317          * @param       $buttonText             Text displayed on the button
 318          * @return      void
 319          * @throws      FormClosedException             If the form is not yet opened
 320          */
 321         public function addInputResetButton ($buttonText) {
 322                 // Is the form opened?
 323                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 324                         // Throw an exception
 325                         throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
 326                 } // END - if
 327
 328                 // Generate the content
 329                 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
 330                         $this->getFormName(),
 331                         $buttonText
 332                 );
 333
 334                 // And add it
 335                 $this->addContentToPreviousGroup($inputContent);
 336         }
 337
 338         /**
 339          * Add a reset input tag to the form or throw an exception if it is not
 340          * yet opened. The field's name will be set as id.
 341          *
 342          * @param       $buttonText             Text displayed on the button
 343          * @return      void
 344          * @throws      FormClosedException             If the form is not yet opened
 345          */
 346         public function addInputSubmitButton ($buttonText) {
 347                 // Is the form opened?
 348                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 349                         // Throw an exception
 350                         throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
 351                 } // END - if
 352
 353                 // Generate the content
 354                 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
 355                         $this->getFormName(),
 356                         $this->getFormName(),
 357                         $buttonText
 358                 );
 359
 360                 // And add it
 361                 $this->addContentToPreviousGroup($inputContent);
 362         }
 363
 364         /**
 365          * Add a form group or close an already opened and open a new one
 366          *
 367          * @param       $groupId        Name of the group or last opened if empty
 368          * @param       $groupText      Text including HTML to show above this group
 369          * @return      void
 370          * @throws      FormClosedException             If no form has been opened before
 371          * @throws      EmptyVariableException  If $groupId is not set
 372          */
 373         public function addFormGroup ($groupId = "", $groupText = "") {
 374                 // Is a form opened?
 375                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 376                         // Throw exception here
 377                         throw new FormClosedException(array($this, $groupId), self::EXCEPTION_CLOSED_FORM);
 378                 } // END - if
 379
 380                 // At least the group name should be set
 381                 if ((empty($groupId)) && (!$this->ifGroupOpenedPreviously())) {
 382                         // Throw exception here
 383                         throw new EmptyVariableException(array($this, 'groupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 384                 } elseif (empty($groupId)) {
 385                         // Close the last opened
 386                         $groupId = $this->getPreviousGroupId();
 387                 }
 388
 389                 // Same group to open?
 390                 if ((!$this->ifGroupOpenedPreviously()) && ($groupId == $this->getPreviousGroupId())) {
 391                         // Abort here silently
 392                         return false;
 393                 } // END - if
 394
 395                 // Initialize content with closing div by default
 396                 $content = "    </div>\n</div><!-- Group - CLOSE //-->";
 397
 398                 // Is this group opened?
 399                 if (!$this->ifGroupOpenedPreviously()) {
 400                         // Begin the div/span blocks
 401                         $content = sprintf("<!-- Group %s - OPEN //-->
 402 <div class=\"group_box\" id=\"%s_group_box\">
 403         <span class=\"group_text\" id=\"%s_group_text\">
 404                 %s
 405         </span>
 406         <div class=\"group_field\" id=\"%s_group_field\">",
 407                                 $groupId,
 408                                 $groupId,
 409                                 $groupId,
 410                                 $groupText,
 411                                 $groupId
 412                         );
 413
 414                         // Switch the state
 415                         $this->openGroupByIdContent($groupId, $content);
 416                 } else {
 417                         // Is a sub group opened?
 418                         if ($this->ifSubGroupOpenedPreviously()) {
 419                                 // Close it here
 420                                 $this->addFormSubGroup();
 421                         } // END - if
 422
 423                         // Get previous group id
 424                         $prevGroupId = $this->getPreviousGroupId();
 425
 426                         // Switch the state
 427                         $this->closePreviousGroupByContent($content);
 428
 429                         // All call it again if the group name is not empty
 430                         if ((!empty($groupId)) && ($groupId != $prevGroupId)) {
 431                                 //* DEBUG: */ echo $groupId."/".$prevGroupId."<br />\n";
 432                                 $this->addFormGroup($groupId, $groupText);
 433                         } // END - if
 434                 }
 435         }
 436
 437         /**
 438          * Add a form sub group or close an already opened and open a new one or
 439          * throws an exception if no group has been opened before or if the sub
 440          * group name is empty.
 441          *
 442          * @param       $subGroupId             Name of the group or last opened if empty
 443          * @param       $subGroupText   Text including HTML to show above this group
 444          * @return      void
 445          * @throws      FormFormClosedException         If no group has been opened before
 446          * @throws      EmptyVariableException          If $subGroupId is not set
 447          */
 448         public function addFormSubGroup ($subGroupId = "", $subGroupText = "") {
 449                 // Is a group opened?
 450                 if (!$this->ifGroupOpenedPreviously()) {
 451                         // Throw exception here
 452                         throw new FormFormClosedException(array($this, $subGroupId), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
 453                 } // END - if
 454
 455                 // At least the sub group name should be set
 456                 if ((empty($subGroupId)) && (!$this->ifSubGroupOpenedPreviously())) {
 457                         // Throw exception here
 458                         throw new EmptyVariableException(array($this, 'subGroupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 459                 } elseif (empty($subGroupId)) {
 460                         // Close the last opened
 461                         $subGroupId = $this->getPreviousSubGroupId();
 462                 }
 463
 464                 // Same sub group to open?
 465                 if ((!$this->ifSubGroupOpenedPreviously()) && ($subGroupId == $this->getPreviousSubGroupId())) {
 466                         // Abort here silently
 467                         return false;
 468                 } // END - if
 469
 470                 // Initialize content with closing div by default
 471                 $content = "    </div>\n</div><!-- Sub group- CLOSE //-->";
 472
 473                 // Is this group opened?
 474                 if (!$this->ifSubGroupOpenedPreviously()) {
 475                         // Begin the span block
 476                         $content = sprintf("<!-- Sub group %s - OPEN //-->
 477 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
 478         <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
 479                 %s
 480         </span>
 481         <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
 482                                 $subGroupId,
 483                                 $subGroupId,
 484                                 $subGroupId,
 485                                 $subGroupText,
 486                                 $subGroupId
 487                         );
 488
 489                         // Switch the state and remeber the name
 490                         $this->openSubGroupByIdContent($subGroupId, $content);
 491                 } else {
 492                         // Get previous sub group id
 493                         $prevSubGroupId = $this->getPreviousSubGroupId();
 494
 495                         // Switch the state
 496                         $this->closePreviousSubGroupByContent($content);
 497
 498                         // All call it again if sub group name is not empty
 499                         if ((!empty($subGroupId)) && ($subGroupId != $prevSubGroupId)) {
 500                                 $this->addFormSubGroup($subGroupId, $subGroupText);
 501                         } // END - if
 502                 }
 503         }
 504
 505         /**
 506          * Add text surrounded by a span block when there is a group opened before
 507          * or else by a div block.
 508          *
 509          * @param       $fieldName                      Field name
 510          * @param       $fieldText                      Text for the field
 511          * @return      void
 512          * @throws      FormClosedException             If the form is not yet opened
 513          */
 514         public function addFieldText ($fieldName, $fieldText) {
 515                 // Is the form opened?
 516                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 517                         // Throw an exception
 518                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 519                 } // END - if
 520
 521                 // Set the block type
 522                 $block = "div";
 523                 if ($this->ifGroupOpenedPreviously()) $block = "span";
 524
 525                 // Generate the content
 526                 $inputContent = sprintf("       <%s id=\"%s_text\">
 527                 %s
 528         </%s>",
 529                         $block,
 530                         $fieldName,
 531                         $fieldText,
 532                         $block
 533                 );
 534
 535                 // And add it
 536                 $this->addContentToPreviousGroup($inputContent);
 537         }
 538
 539         /**
 540          * Add text (notes) surrounded by a div block. Still opened groups or sub
 541          * groups will be automatically closed.
 542          *
 543          * @param       $noteId         Id for this note
 544          * @param       $formNotes      The form notes we shell addd
 545          * @return      void
 546          * @throws      FormClosedException             If the form is not yet opened
 547          */
 548         public function addFormNote ($noteId, $formNotes) {
 549                 // Is the form opened?
 550                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 551                         // Throw an exception
 552                         throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
 553                 } // END - if
 554
 555                 // Is a group open?
 556                 if ($this->ifGroupOpenedPreviously()) {
 557                         // Then automatically close it here
 558                         $this->addFormGroup();
 559                 } // END - if
 560
 561                 // Generate the content
 562                 $inputContent = sprintf("       <div id=\"form_note_%s\">
 563                 %s
 564         </div>",
 565                         $noteId,
 566                         $formNotes
 567                 );
 568
 569                 // And add it
 570                 $this->addContentToPreviousGroup($inputContent);
 571         }
 572
 573         /**
 574          * Adds a selection box as a sub group to the form. Do not box this into
 575          * another sub group. Sub-sub groups are not (yet) supported.
 576          *
 577          * @param       $selectId               Id of the selection box
 578          * @param       $firstEntry             Content to be added as first non-selectable entry
 579          * @return      void
 580          * @throws      FormClosedException             If the form is not yet opened
 581          */
 582         public function addInputSelectField ($selectId, $firstEntry) {
 583                 // Is the form group opened?
 584                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 585                         // Throw an exception
 586                         throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
 587                 } // END - if
 588
 589                 // Shall we close or open the sub group?
 590                 if ((!$this->ifSubGroupOpenedPreviously()) && ($this->getPreviousSubGroupId() !== $selectId)) {
 591                         // Initialize first entry (which might be non-selectable if content is provided
 592                         if (!empty($firstEntry)) {
 593                                 // Add selection around it
 594                                 $firstEntry = sprintf("<option value=\"invalid\" disabled=\"disabled\">%s</option>\n",
 595                                         $firstEntry
 596                                 );
 597                         } // END - if
 598
 599                         // Construct the opening select tag
 600                         $content = sprintf("<select class=\"select_box\" id=\"%s_%s\" name=\"%s\">\n%s",
 601                                 $this->getFormName(),
 602                                 $selectId,
 603                                 $selectId,
 604                                 $firstEntry
 605                         );
 606
 607                         // Open the sub group
 608                         $this->openSubGroupByIdContent($selectId, $content);
 609                 } elseif ($this->getPreviousSubGroupId() != $selectId) {
 610                         // Something went wrong!
 611                         $this->debugInstance();
 612                 } else {
 613                         // Close the sub group
 614                         $this->closePreviousSubGroupByContent("</select>");
 615                 }
 616         }
 617
 618         /**
 619          * Adds a non-selectable sub option to a previously added selection box.
 620          * This method does *not* validate if there is already a sub option added
 621          * with the same name. We need to finish this here!
 622          *
 623          * @param       $subName        Name of the sub action
 624          * @param       $subValue       Value of the sub action
 625          * @return      void
 626          * @throws      HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found
 627          * @todo        Add checking if sub option is already added
 628          */
 629         public function addSelectSubOption ($subName, $subValue) {
 630                 // Is there a sub group (shall be a selection box!)
 631                 if (!$this->ifSubGroupOpenedPreviously()) {
 632                         // Then throw an exception here
 633                         throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
 634                 } // END - if
 635
 636                 // Render the content
 637                 $content = sprintf("<option value=\"invalid\" class=\"suboption suboption_%s\" disabled=\"disabled\">%s</option>\n",
 638                         $subName,
 639                         $subValue
 640                 );
 641
 642                 // Add the content to the previously opened sub group
 643                 $this->addContentToPreviousGroup($content);
 644         }
 645
 646         /**
 647          * Adds a selectable option to a previously added selection box. This method
 648          * does *not* validate if there is already a sub option added with the same
 649          * name. We need to finish this here!
 650          *
 651          * @param       $optionName     Name of the sub action
 652          * @param       $optionValue    Value of the sub action
 653          * @return      void
 654          * @throws      HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found
 655          * @todo        Add checking if sub option is already added
 656          */
 657         public function addSelectOption ($optionName, $optionValue) {
 658                 // Is there a sub group (shall be a selection box!)
 659                 if (!$this->ifSubGroupOpenedPreviously()) {
 660                         // Then throw an exception here
 661                         throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
 662                 } // END - if
 663
 664                 // Render the content
 665                 $content = sprintf("<option value=\"%s\" class=\"option option_%s\">%s</option>\n",
 666                         $optionName,
 667                         $optionName,
 668                         $optionValue
 669                 );
 670
 671                 // Add the content to the previously opened sub group
 672                 $this->addContentToPreviousGroup($content);
 673         }
 674
 675         /**
 676          * Adds a pre-configured CAPTCHA
 677          *
 678          * @return      void
 679          */
 680         public function addCaptcha () {
 681                 // Get last executed pre filter
 682                 $extraInstance = Registry::getRegistry()->getInstance('extra');
 683
 684                 // Get a configured instance
 685                 $captchaInstance = ObjectFactory::createObjectByConfiguredName($this->getFormName().'_captcha', array($this, $extraInstance));
 686
 687                 // Initiate the CAPTCHA
 688                 $captchaInstance->initiateCaptcha();
 689
 690                 // Render the CAPTCHA code
 691                 $captchaInstance->renderCode();
 692
 693                 // Get the content and add it to the helper
 694                 $this->addContentToPreviousGroup($captchaInstance->renderContent());
 695         }
 696
 697         /**
 698          * Enables/disables the form tag usage
 699          *
 700          * @param       $formEnabled    Wether form is enabled or disabled
 701          * @return      void
 702          */
 703         public final function enableForm ($formEnabled = true) {
 704                 $this->formEnabled = (bool) $formEnabled;
 705         }
 706
 707         /**
 708          * Setter for form name
 709          *
 710          * @param       $formName       Name of this form
 711          * @return      void
 712          */
 713         public final function setFormName ($formName) {
 714                 $this->formName = (string) $formName;
 715         }
 716
 717         /**
 718          * Getter for form name
 719          *
 720          * @return      $formName       Name of this form
 721          */
 722         public final function getFormName () {
 723                 return $this->formName;
 724         }
 725
 726         /**
 727          * Checks wether the registration requires a valid email address
 728          *
 729          * @return      $required       Wether the email address is required
 730          */
 731         public function ifRegisterRequiresEmailVerification () {
 732                 $required = ($this->getConfigInstance()->readConfig('register_requires_email') === "Y");
 733                 return $required;
 734         }
 735
 736         /**
 737          * Checks wether profile data shall be asked
 738          *
 739          * @return      $required       Wether profile data shall be asked
 740          */
 741         public function ifRegisterIncludesProfile () {
 742                 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') === "Y");
 743                 return $required;
 744         }
 745
 746         /**
 747          * Checks wether this form is secured by a CAPTCHA
 748          *
 749          * @return      $isSecured      Wether this form is secured by a CAPTCHA
 750          */
 751         public function ifFormSecuredWithCaptcha () {
 752                 $isSecured = ($this->getConfigInstance()->readConfig($this->getFormName().'_captcha_secured') === "Y");
 753                 return $isSecured;
 754         }
 755
 756         /**
 757          * Flushs the content out (not yet secured against open forms, etc.!) or
 758          * close the form automatically
 759          *
 760          * @return      void
 761          * @throws      FormOpenedException             If the form is still open
 762          */
 763         public function flushContent () {
 764                 // Is the form still open?
 765                 if (($this->formOpened === true) && ($this->formEnabled === true)) {
 766                         // Close the form automatically
 767                         $this->addFormTag();
 768                 } elseif ($this->formEnabled === false) {
 769                         if ($this->ifSubGroupOpenedPreviously()) {
 770                                 // Close sub group
 771                                 $this->addFormSubGroup();
 772                         } elseif ($this->ifGroupOpenedPreviously()) {
 773                                 // Close group
 774                                 $this->addFormGroup();
 775                         }
 776                 }
 777
 778                 // Send content to template engine
 779                 //* DEBUG: */ echo __METHOD__.": form=".$this->getFormName().", size=".strlen($this->renderContent())."<br />\n";
 780                 $this->getTemplateInstance()->assignVariable($this->getFormName(), $this->renderContent());
 781         }
 782 }
 783
 784 // [EOF]
 785 ?>