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() === false)) {
 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() === false) && ($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() === false) {
 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, "div");
 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 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 sub group
 440          * 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() === false) {
 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() === false)) {
 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() === false) && ($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() === false) {
 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, "div");
 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                 // Generate the content
 556                 $inputContent = sprintf("       <div id=\"form_note_%s\">
 557                 %s
 558         </div>",
 559                         $noteId,
 560                         $formNotes
 561                 );
 562
 563                 // And add it
 564                 $this->addContentToPreviousGroup($inputContent);
 565         }
 566
 567         /**
 568          * Adds a selection box as a sub group to the form. Do not box this into
 569          * another sub group. Sub-sub groups are not (yet) supported.
 570          *
 571          * @param       $selectId               Id of the selection box
 572          * @param       $firstEntry             Content to be added as first non-selectable entry
 573          * @return      void
 574          * @throws      FormClosedException             If the form is not yet opened
 575          */
 576         public function addInputSelectField ($selectId, $firstEntry) {
 577                 // Is the form group opened?
 578                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
 579                         // Throw an exception
 580                         throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
 581                 } // END - if
 582
 583                 // Shall we close or open the sub group?
 584                 if (($this->ifSubGroupOpenedPreviously() === false) && ($this->getPreviousSubGroupId() !== $selectId)) {
 585                         // Initialize first entry (which might be non-selectable if content is provided
 586                         if (!empty($firstEntry)) {
 587                                 // Add selection around it
 588                                 $firstEntry = sprintf("<option value=\"invalid\" disabled=\"disabled\">%s</option>\n",
 589                                         $firstEntry
 590                                 );
 591                         } // END - if
 592
 593                         // Construct the opening select tag
 594                         $content = sprintf("<select class=\"select_box\" id=\"%s_%s\" name=\"%s\">\n%s",
 595                                 $this->getFormName(),
 596                                 $selectId,
 597                                 $selectId,
 598                                 $firstEntry
 599                         );
 600
 601                         // Open the sub group
 602                         $this->openSubGroupByIdContent($selectId, $content, "select");
 603                 } elseif ($this->getPreviousSubGroupId() != $selectId) {
 604                         // Something went wrong!
 605                         $this->debugInstance(__METHOD__."(): Previous sub group id {$this->getPreviousSubGroupId()} does not match current id {$selectId}.");
 606                 } else {
 607                         // Close the sub group
 608                         $this->closePreviousSubGroupByContent("</select>");
 609                 }
 610         }
 611
 612         /**
 613          * Adds a non-selectable sub option to a previously added selection box.
 614          * This method does *not* validate if there is already a sub option added
 615          * with the same name. We need to finish this here!
 616          *
 617          * @param       $subName        Name of the sub action
 618          * @param       $subValue       Value of the sub action
 619          * @return      void
 620          * @throws      HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found
 621          * @todo        Add checking if sub option is already added
 622          */
 623         public function addSelectSubOption ($subName, $subValue) {
 624                 // Is there a sub group (shall be a selection box!)
 625                 if ($this->ifSubGroupOpenedPreviously() === false) {
 626                         // Then throw an exception here
 627                         throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
 628                 } // END - if
 629
 630                 // Render the content
 631                 $content = sprintf("<option value=\"invalid\" class=\"suboption suboption_%s\" disabled=\"disabled\">%s</option>\n",
 632                         $subName,
 633                         $subValue
 634                 );
 635
 636                 // Add the content to the previously opened sub group
 637                 $this->addContentToPreviousGroup($content);
 638         }
 639
 640         /**
 641          * Adds a selectable option to a previously added selection box. This method
 642          * does *not* validate if there is already a sub option added with the same
 643          * name. We need to finish this here!
 644          *
 645          * @param       $optionName     Name of the sub action
 646          * @param       $optionValue    Value of the sub action
 647          * @return      void
 648          * @throws      HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found
 649          * @todo        Add checking if sub option is already added
 650          */
 651         public function addSelectOption ($optionName, $optionValue) {
 652                 // Is there a sub group (shall be a selection box!)
 653                 if ($this->ifSubGroupOpenedPreviously() === false) {
 654                         // Then throw an exception here
 655                         throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
 656                 } // END - if
 657
 658                 // Render the content
 659                 $content = sprintf("<option value=\"%s\" class=\"option option_%s\">%s</option>\n",
 660                         $optionName,
 661                         $optionName,
 662                         $optionValue
 663                 );
 664
 665                 // Add the content to the previously opened sub group
 666                 $this->addContentToPreviousGroup($content);
 667         }
 668
 669         /**
 670          * Adds a pre-configured CAPTCHA
 671          *
 672          * @return      void
 673          */
 674         public function addCaptcha () {
 675                 // Get last executed pre filter
 676                 $extraInstance = Registry::getRegistry()->getInstance('extra');
 677
 678                 // Get a configured instance
 679                 $captchaInstance = ObjectFactory::createObjectByConfiguredName($this->getFormName().'_captcha', array($this, $extraInstance));
 680
 681                 // Initiate the CAPTCHA
 682                 $captchaInstance->initiateCaptcha();
 683
 684                 // Render the CAPTCHA code
 685                 $captchaInstance->renderCode();
 686
 687                 // Get the content and add it to the helper
 688                 $this->addContentToPreviousGroup($captchaInstance->renderContent());
 689         }
 690
 691         /**
 692          * Enables/disables the form tag usage
 693          *
 694          * @param       $formEnabled    Wether form is enabled or disabled
 695          * @return      void
 696          */
 697         public final function enableForm ($formEnabled = true) {
 698                 $this->formEnabled = (bool) $formEnabled;
 699         }
 700
 701         /**
 702          * Setter for form name
 703          *
 704          * @param       $formName       Name of this form
 705          * @return      void
 706          */
 707         public final function setFormName ($formName) {
 708                 $this->formName = (string) $formName;
 709         }
 710
 711         /**
 712          * Getter for form name
 713          *
 714          * @return      $formName       Name of this form
 715          */
 716         public final function getFormName () {
 717                 return $this->formName;
 718         }
 719
 720         /**
 721          * Checks wether the registration requires a valid email address
 722          *
 723          * @return      $required       Wether the email address is required
 724          */
 725         public function ifRegisterRequiresEmailVerification () {
 726                 $required = ($this->getConfigInstance()->readConfig('register_requires_email') === "Y");
 727                 return $required;
 728         }
 729
 730         /**
 731          * Checks wether profile data shall be asked
 732          *
 733          * @return      $required       Wether profile data shall be asked
 734          */
 735         public function ifRegisterIncludesProfile () {
 736                 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') === "Y");
 737                 return $required;
 738         }
 739
 740         /**
 741          * Checks wether this form is secured by a CAPTCHA
 742          *
 743          * @return      $isSecured      Wether this form is secured by a CAPTCHA
 744          */
 745         public function ifFormSecuredWithCaptcha () {
 746                 $isSecured = ($this->getConfigInstance()->readConfig($this->getFormName().'_captcha_secured') === "Y");
 747                 return $isSecured;
 748         }
 749
 750         /**
 751          * Flushs the content out (not yet secured against open forms, etc.!) or
 752          * close the form automatically
 753          *
 754          * @return      void
 755          * @throws      FormOpenedException             If the form is still open
 756          */
 757         public function flushContent () {
 758                 // Is the form still open?
 759                 if (($this->formOpened === true) && ($this->formEnabled === true)) {
 760                         // Close the form automatically
 761                         $this->addFormTag();
 762                 } elseif ($this->formEnabled === false) {
 763                         if ($this->ifSubGroupOpenedPreviously()) {
 764                                 // Close sub group
 765                                 $this->addFormSubGroup();
 766                         } elseif ($this->ifGroupOpenedPreviously()) {
 767                                 // Close group
 768                                 $this->addFormGroup();
 769                         }
 770                 }
 771
 772                 // Send content to template engine
 773                 //* DEBUG: */ echo __METHOD__.": form=".$this->getFormName().", size=".strlen($this->renderContent())."<br />\n";
 774                 $this->getTemplateInstance()->assignVariable($this->getFormName(), $this->renderContent());
 775         }
 776 }
 777
 778 // [EOF]
 779 ?>