inc/main/classes/helper/html/forms/class_HtmlFormHelper.php

   1 <?php
   2 // Own namespace
   3 namespace CoreFramework\Helper;
   4
   5 // Import framework stuff
   6 use CoreFramework\Factory\ObjectFactory;
   7 use CoreFramework\Generic\NullPointerException;
   8 use CoreFramework\Registry\Generic\Registry;
   9 use CoreFramework\Template\CompileableTemplate;
  10
  11 /**
  12  * A helper for constructing web forms
  13  *
  14  * @author              Roland Haeder <webmaster@shipsimu.org>
  15  * @version             0.0.0
  16  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
  17  * @license             GNU GPL 3.0 or any newer version
  18  * @link                http://www.shipsimu.org
  19  *
  20  * This program is free software: you can redistribute it and/or modify
  21  * it under the terms of the GNU General Public License as published by
  22  * the Free Software Foundation, either version 3 of the License, or
  23  * (at your option) any later version.
  24  *
  25  * This program is distributed in the hope that it will be useful,
  26  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  27  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  28  * GNU General Public License for more details.
  29  *
  30  * You should have received a copy of the GNU General Public License
  31  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  32  */
  33 class HtmlFormHelper extends BaseHtmlHelper implements HelpableTemplate {
  34         /**
  35          * Whether the form tag is opened (keep at FALSE or else your forms will
  36          * never work!)
  37          */
  38         private $formOpened = FALSE;
  39
  40         /**
  41          * Name of the form
  42          */
  43         private $formName = '';
  44
  45         /**
  46          * Whether form tag is enabled (default: TRUE)
  47          */
  48         private $formEnabled = TRUE;
  49
  50         // Class Constants
  51         const EXCEPTION_FORM_NAME_INVALID       = 0x120;
  52         const EXCEPTION_CLOSED_FORM             = 0x121;
  53         const EXCEPTION_OPENED_FORM             = 0x122;
  54         const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x123;
  55
  56         /**
  57          * Protected constructor
  58          *
  59          * @return      void
  60          */
  61         protected function __construct () {
  62                 // Call parent constructor
  63                 parent::__construct(__CLASS__);
  64         }
  65
  66         /**
  67          * Creates the helper class with the given template engine instance and form name
  68          *
  69          * @param       $templateInstance       An instance of a valid template engine
  70          * @param       $formName                       Name of the form
  71          * @param       $formId                         Value for 'id' attribute (default: $formName)
  72          * @param       $withForm                       Whether include the form tag
  73          * @return      $helperInstance         A preparedf instance of this helper
  74          */
  75         public static final function createHtmlFormHelper (CompileableTemplate $templateInstance, $formName, $formId = FALSE, $withForm = TRUE) {
  76                 // Get new instance
  77                 $helperInstance = new HtmlFormHelper();
  78
  79                 // Set template instance
  80                 $helperInstance->setTemplateInstance($templateInstance);
  81
  82                 // Is the form id not set?
  83                 if ($formId === FALSE) {
  84                         // Use form id from form name
  85                         $formId = $formName;
  86                 } // END - if
  87
  88                 // Set form name
  89                 $helperInstance->setFormName($formName);
  90
  91                 // A form-less field may say 'FALSE' here...
  92                 if ($withForm === TRUE) {
  93                         // Create the form
  94                         $helperInstance->addFormTag($formName, $formId);
  95                 } else {
  96                         // Disable form
  97                         $helperInstance->enableForm(FALSE);
  98                 }
  99
 100                 // Return the prepared instance
 101                 return $helperInstance;
 102         }
 103
 104         /**
 105          * Add the form tag or close it an already opened form tag
 106          *
 107          * @param       $formName       Name of the form (default: FALSE)
 108          * @param       $formId         Id of the form (attribute 'id'; default: FALSE)
 109          * @return      void
 110          * @throws      InvalidFormNameException        If the form name is invalid ( = FALSE)
 111          * @todo        Add some unique PIN here to bypass problems with some browser and/or extensions
 112          */
 113         public function addFormTag ($formName = FALSE, $formId = FALSE) {
 114                 // When the form is not yet opened at least form name must be valid
 115                 if (($this->formOpened === FALSE) && ($formName === FALSE)) {
 116                         // Thrown an exception
 117                         throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
 118                 } // END - if
 119
 120                 // Close the form is default
 121                 $formContent = '</form>';
 122
 123                 // Check whether we shall open or close the form
 124                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 125                         // Add HTML code
 126                         $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
 127                                 $formName,
 128                                 $this->getConfigInstance()->getConfigEntry('base_url'),
 129                                 $this->getConfigInstance()->getConfigEntry('form_action'),
 130                                 $this->getConfigInstance()->getConfigEntry('form_method'),
 131                                 $this->getConfigInstance()->getConfigEntry('form_target')
 132                         );
 133
 134                         // Add form id as well
 135                         $formContent .= sprintf(" id=\"%s_form\"",
 136                                 $formId
 137                         );
 138
 139                         // Add close bracket
 140                         $formContent .= '>';
 141
 142                         // Open the form and remeber the form name
 143                         $this->formOpened = TRUE;
 144
 145                         // Add it to the content
 146                         $this->addHeaderContent($formContent);
 147                 } else {
 148                         // Add the hidden field required to identify safely this form
 149                         $this->addInputHiddenField('form', $this->getFormName());
 150
 151                         // Is a group open?
 152                         if ($this->ifGroupOpenedPreviously()) {
 153                                 // Then automatically close it here
 154                                 $this->addFormGroup();
 155                         } // END - if
 156
 157                         // Simply close it
 158                         $this->formOpened = FALSE;
 159
 160                         // Add it to the content
 161                         $this->addFooterContent($formContent);
 162                 }
 163         }
 164
 165         /**
 166          * Add a text input tag to the form or throw an exception if it is not yet
 167          * opened. The field's name will be set as id.
 168          *
 169          * @param       $fieldName              Input field name
 170          * @param       $fieldValue             Input default value (default: empty)
 171          * @return      void
 172          * @throws      FormClosedException             If the form is not yet opened
 173          */
 174         public function addInputTextField ($fieldName, $fieldValue = '') {
 175                 // Is the form opened?
 176                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 177                         // Throw an exception
 178                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 179                 } // END - if
 180
 181                 // Generate the content
 182                 $inputContent = sprintf("<input type=\"text\" class=\"textfield %s_field\" name=\"%s\" value=\"%s\" />",
 183                         $fieldName,
 184                         $fieldName,
 185                         $fieldValue
 186                 );
 187
 188                 // And add it maybe with a 'li' tag
 189                 $this->addContentToPreviousGroup($inputContent);
 190         }
 191
 192         /**
 193          * Add a text input tag to the form with pre-loaded default value
 194          *
 195          * @param       $fieldName      Input field name
 196          * @return      void
 197          */
 198         public function addInputTextFieldWithDefault ($fieldName) {
 199                 // Get the value from instance
 200                 $fieldValue = $this->getValueField($fieldName);
 201                 //* DEBUG: */ print __METHOD__.':'.$fieldName.'='.$fieldValue."<br />\n";
 202
 203                 // Add the text field
 204                 $this->addInputTextField($fieldName, $fieldValue);
 205         }
 206
 207         /**
 208          * Add a password input tag to the form or throw an exception if it is not
 209          * yet opened. The field's name will be set as id.
 210          *
 211          * @param       $fieldName              Input field name
 212          * @param       $fieldValue             Input default value (default: empty)
 213          * @return      void
 214          * @throws      FormClosedException             If the form is not yet opened
 215          */
 216         public function addInputPasswordField ($fieldName, $fieldValue = '') {
 217                 // Is the form opened?
 218                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 219                         // Throw an exception
 220                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 221                 } // END - if
 222
 223                 // Generate the content
 224                 $inputContent = sprintf("<input type=\"password\" class=\"password %s_field\" name=\"%s\" value=\"%s\" />",
 225                         $fieldName,
 226                         $fieldName,
 227                         $fieldValue
 228                 );
 229
 230                 // And add it
 231                 $this->addContentToPreviousGroup($inputContent);
 232         }
 233
 234         /**
 235          * Add a hidden input tag to the form or throw an exception if it is not
 236          * yet opened. The field's name will be set as id.
 237          *
 238          * @param       $fieldName              Input field name
 239          * @param       $fieldValue             Input default value (default: empty)
 240          * @return      void
 241          * @throws      FormClosedException             If the form is not yet opened
 242          */
 243         public function addInputHiddenField ($fieldName, $fieldValue = '') {
 244                 // Is the form opened?
 245                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 246                         // Throw an exception
 247                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 248                 } // END - if
 249
 250                 // Generate the content
 251                 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
 252                         $fieldName,
 253                         $fieldValue
 254                 );
 255
 256                 // And add it
 257                 $this->addContentToPreviousGroup($inputContent);
 258         }
 259
 260         /**
 261          * Add a hidden input tag to the form with pre-loaded default value
 262          *
 263          * @param       $fieldName      Input field name
 264          * @return      void
 265          */
 266         public function addInputHiddenFieldWithDefault ($fieldName) {
 267                 // Get the value from instance
 268                 $fieldValue = $this->getValueField($fieldName);
 269                 //* DEBUG: */ print __METHOD__.':'.$fieldName.'='.$fieldValue."<br />\n";
 270
 271                 // Add the text field
 272                 $this->addInputHiddenField($fieldName, $fieldValue);
 273         }
 274
 275         /**
 276          * Add a hidden input tag to the form with configuration value
 277          *
 278          * @param       $fieldName      Input field name
 279          * @param       $prefix         Prefix for configuration without trailing _
 280          * @return      void
 281          */
 282         public function addInputHiddenConfiguredField ($fieldName, $prefix) {
 283                 // Get the value from instance
 284                 $fieldValue = $this->getConfigInstance()->getConfigEntry("{$prefix}_{$fieldName}");
 285                 //* DEBUG: */ print __METHOD__.':'.$fieldName.'='.$fieldValue."<br />\n";
 286
 287                 // Add the text field
 288                 $this->addInputHiddenField($fieldName, $fieldValue);
 289         }
 290
 291         /**
 292          * Add a checkbox input tag to the form or throw an exception if it is not
 293          * yet opened. The field's name will be set as id.
 294          *
 295          * @param       $fieldName              Input field name
 296          * @param       $fieldChecked   Whether the field is checked (defaut: checked)
 297          * @return      void
 298          * @throws      FormClosedException             If the form is not yet opened
 299          */
 300         public function addInputCheckboxField ($fieldName, $fieldChecked = TRUE) {
 301                 // Is the form opened?
 302                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 303                         // Throw an exception
 304                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 305                 } // END - if
 306
 307                 // Set whether the check box is checked...
 308                 $checked = " checked=\"checked\"";
 309                 if ($fieldChecked === FALSE) $checked = ' ';
 310
 311                 // Generate the content
 312                 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox %s_field\" value=\"1\"%s/>",
 313                         $fieldName,
 314                         $fieldName,
 315                         $checked
 316                 );
 317
 318                 // And add it
 319                 $this->addContentToPreviousGroup($inputContent);
 320         }
 321
 322         /**
 323          * Add a reset input tag to the form or throw an exception if it is not
 324          * yet opened. The field's name will be set as id.
 325          *
 326          * @param       $buttonText             Text displayed on the button
 327          * @return      void
 328          * @throws      FormClosedException             If the form is not yet opened
 329          */
 330         public function addInputResetButton ($buttonText) {
 331                 // Is the form opened?
 332                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 333                         // Throw an exception
 334                         throw new FormClosedException (array($this, 'reset'), self::EXCEPTION_CLOSED_FORM);
 335                 } // END - if
 336
 337                 // Generate the content
 338                 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
 339                         $this->getFormName(),
 340                         $buttonText
 341                 );
 342
 343                 // And add it
 344                 $this->addContentToPreviousGroup($inputContent);
 345         }
 346
 347         /**
 348          * Add a reset input tag to the form or throw an exception if it is not
 349          * yet opened. The field's name will be set as id.
 350          *
 351          * @param       $buttonText             Text displayed on the button
 352          * @return      void
 353          * @throws      FormClosedException             If the form is not yet opened
 354          */
 355         public function addInputSubmitButton ($buttonText) {
 356                 // Is the form opened?
 357                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 358                         // Throw an exception
 359                         throw new FormClosedException (array($this, 'submit'), self::EXCEPTION_CLOSED_FORM);
 360                 } // END - if
 361
 362                 // Generate the content
 363                 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
 364                         $this->getFormName(),
 365                         $this->getFormName(),
 366                         $buttonText
 367                 );
 368
 369                 // And add it
 370                 $this->addContentToPreviousGroup($inputContent);
 371         }
 372
 373         /**
 374          * Add a form group or close an already opened and open a new one
 375          *
 376          * @param       $groupId        Name of the group or last opened if empty
 377          * @param       $groupText      Text including HTML to show above this group
 378          * @return      void
 379          * @throws      FormClosedException             If no form has been opened before
 380          * @throws      EmptyVariableException  If $groupId is not set
 381          */
 382         public function addFormGroup ($groupId = '', $groupText = '') {
 383                 // Is a form opened?
 384                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 385                         // Throw exception here
 386                         throw new FormClosedException(array($this, $groupId), self::EXCEPTION_CLOSED_FORM);
 387                 } // END - if
 388
 389                 // At least the group name should be set
 390                 if ((empty($groupId)) && ($this->ifGroupOpenedPreviously() === FALSE)) {
 391                         // Throw exception here
 392                         throw new EmptyVariableException(array($this, 'groupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 393                 } elseif (empty($groupId)) {
 394                         // Close the last opened
 395                         $groupId = $this->getPreviousGroupId();
 396                 }
 397
 398                 // Same group to open?
 399                 if (($this->ifGroupOpenedPreviously() === FALSE) && ($groupId === $this->getPreviousGroupId())) {
 400                         // Abort here silently
 401                         return FALSE;
 402                 } // END - if
 403
 404                 // Initialize content with closing div by default
 405                 $content = "    </div>\n</div><!-- Group - CLOSE //-->";
 406
 407                 // Is this group opened?
 408                 if ($this->ifGroupOpenedPreviously() === FALSE) {
 409                         // Begin the div/span blocks
 410                         $content = sprintf("<!-- Group %s - OPEN //-->
 411 <div class=\"group_box\" id=\"%s_group_box\">
 412         <span class=\"group_text\" id=\"%s_group_text\">
 413                 %s
 414         </span>
 415         <div class=\"group_field\" id=\"%s_group_field\">",
 416                                 $groupId,
 417                                 $groupId,
 418                                 $groupId,
 419                                 $groupText,
 420                                 $groupId
 421                         );
 422
 423                         // Switch the state
 424                         $this->openGroupByIdContent($groupId, $content, "div");
 425                 } else {
 426                         // Is a sub group opened?
 427                         if ($this->ifSubGroupOpenedPreviously()) {
 428                                 // Close it here
 429                                 $this->addFormSubGroup();
 430                         } // END - if
 431
 432                         // Get previous group id
 433                         $prevGroupId = $this->getPreviousGroupId();
 434
 435                         // Switch the state
 436                         $this->closePreviousGroupByContent($content);
 437
 438                         // All call it again if group name is not empty
 439                         if ((!empty($groupId)) && ($groupId != $prevGroupId)) {
 440                                 //* DEBUG: */ echo $groupId.'/'.$prevGroupId."<br />\n";
 441                                 $this->addFormGroup($groupId, $groupText);
 442                         } // END - if
 443                 }
 444         }
 445
 446         /**
 447          * Add a form sub group or close an already opened and open a new one or
 448          * throws an exception if no group has been opened before or if sub group
 449          * name is empty.
 450          *
 451          * @param       $subGroupId             Name of the group or last opened if empty
 452          * @param       $subGroupText   Text including HTML to show above this group
 453          * @return      void
 454          * @throws      FormFormClosedException         If no group has been opened before
 455          * @throws      EmptyVariableException          If $subGroupId is not set
 456          */
 457         public function addFormSubGroup ($subGroupId = '', $subGroupText = '') {
 458                 // Is a group opened?
 459                 if ($this->ifGroupOpenedPreviously() === FALSE) {
 460                         // Throw exception here
 461                         throw new FormFormClosedException(array($this, $subGroupId), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
 462                 } // END - if
 463
 464                 // At least the sub group name should be set
 465                 if ((empty($subGroupId)) && ($this->ifSubGroupOpenedPreviously() === FALSE)) {
 466                         // Throw exception here
 467                         throw new EmptyVariableException(array($this, 'subGroupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 468                 } elseif (empty($subGroupId)) {
 469                         // Close the last opened
 470                         $subGroupId = $this->getPreviousSubGroupId();
 471                 }
 472
 473                 // Same sub group to open?
 474                 if (($this->ifSubGroupOpenedPreviously() === FALSE) && ($subGroupId == $this->getPreviousSubGroupId())) {
 475                         // Abort here silently
 476                         return FALSE;
 477                 } // END - if
 478
 479                 // Initialize content with closing div by default
 480                 $content = "    </div>\n</div><!-- Sub group- CLOSE //-->";
 481
 482                 // Is this group opened?
 483                 if ($this->ifSubGroupOpenedPreviously() === FALSE) {
 484                         // Begin the span block
 485                         $content = sprintf("<!-- Sub group %s - OPEN //-->
 486 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
 487         <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
 488                 %s
 489         </span>
 490         <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
 491                                 $subGroupId,
 492                                 $subGroupId,
 493                                 $subGroupId,
 494                                 $subGroupText,
 495                                 $subGroupId
 496                         );
 497
 498                         // Switch the state and remeber the name
 499                         $this->openSubGroupByIdContent($subGroupId, $content, "div");
 500                 } else {
 501                         // Get previous sub group id
 502                         $prevSubGroupId = $this->getPreviousSubGroupId();
 503
 504                         // Switch the state
 505                         $this->closePreviousSubGroupByContent($content);
 506
 507                         // All call it again if sub group name is not empty
 508                         if ((!empty($subGroupId)) && ($subGroupId != $prevSubGroupId)) {
 509                                 $this->addFormSubGroup($subGroupId, $subGroupText);
 510                         } // END - if
 511                 }
 512         }
 513
 514         /**
 515          * Add text surrounded by a span block when there is a group opened before
 516          * or else by a div block.
 517          *
 518          * @param       $fieldName                      Field name
 519          * @param       $fieldText                      Text for the field
 520          * @return      void
 521          * @throws      FormClosedException             If the form is not yet opened
 522          */
 523         public function addFieldText ($fieldName, $fieldText) {
 524                 // Is the form opened?
 525                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 526                         // Throw an exception
 527                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 528                 } // END - if
 529
 530                 // Set the block type
 531                 $block = 'div';
 532                 if ($this->ifGroupOpenedPreviously()) $block = 'span';
 533
 534                 // Generate the content
 535                 $inputContent = sprintf("       <%s id=\"%s_text\">
 536                 %s
 537         </%s>",
 538                         $block,
 539                         $fieldName,
 540                         $fieldText,
 541                         $block
 542                 );
 543
 544                 // And add it
 545                 $this->addContentToPreviousGroup($inputContent);
 546         }
 547
 548         /**
 549          * Add text (notes) surrounded by a div block. Still opened groups or sub
 550          * groups will be automatically closed.
 551          *
 552          * @param       $noteId         Id for this note
 553          * @param       $formNotes      The form notes we shell addd
 554          * @return      void
 555          * @throws      FormClosedException             If the form is not yet opened
 556          */
 557         public function addFormNote ($noteId, $formNotes) {
 558                 // Is the form opened?
 559                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 560                         // Throw an exception
 561                         throw new FormClosedException (array($this, 'form_notes'), self::EXCEPTION_CLOSED_FORM);
 562                 } // END - if
 563
 564                 // Generate the content
 565                 $inputContent = sprintf("       <div id=\"form_note_%s\">
 566                 %s
 567         </div>",
 568                         $noteId,
 569                         $formNotes
 570                 );
 571
 572                 // And add it
 573                 $this->addContentToPreviousGroup($inputContent);
 574         }
 575
 576         /**
 577          * Adds a selection box as a sub group to the form. Do not box this into
 578          * another sub group. Sub-sub groups are not (yet) supported.
 579          *
 580          * @param       $selectId               Id of the selection box
 581          * @param       $firstEntry             Content to be added as first non-selectable entry
 582          * @return      void
 583          * @throws      FormClosedException             If the form is not yet opened
 584          */
 585         public function addInputSelectField ($selectId, $firstEntry) {
 586                 // Is the form group opened?
 587                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 588                         // Throw an exception
 589                         throw new FormClosedException (array($this, 'form_notes'), self::EXCEPTION_CLOSED_FORM);
 590                 } // END - if
 591
 592                 // Shall we close or open the sub group?
 593                 if (($this->ifSubGroupOpenedPreviously() === FALSE) && ($this->getPreviousSubGroupId() !== $selectId)) {
 594                         // Initialize first entry (which might be non-selectable if content is provided
 595                         if (!empty($firstEntry)) {
 596                                 // Add selection around it
 597                                 $firstEntry = sprintf("<option value=\"invalid\" disabled=\"disabled\">%s</option>\n",
 598                                         $firstEntry
 599                                 );
 600                         } // END - if
 601
 602                         // Construct the opening select tag
 603                         $content = sprintf("<select class=\"select_box\" id=\"%s_%s\" name=\"%s\">\n%s",
 604                                 $this->getFormName(),
 605                                 $selectId,
 606                                 $selectId,
 607                                 $firstEntry
 608                         );
 609
 610                         // Open the sub group
 611                         $this->openSubGroupByIdContent($selectId, $content, "select");
 612                 } elseif ($this->getPreviousSubGroupId() != $selectId) {
 613                         // Something went wrong!
 614                         $this->debugInstance(__METHOD__."(): Previous sub group id {$this->getPreviousSubGroupId()} does not match current id {$selectId}.");
 615                 } else {
 616                         // Close the sub group
 617                         $this->closePreviousSubGroupByContent("</select>");
 618                 }
 619         }
 620
 621         /**
 622          * Adds a non-selectable sub option to a previously added selection box.
 623          * This method does *not* validate if there is already a sub option added
 624          * with the same name. We need to finish this here!
 625          *
 626          * @param       $subName        Name of the sub action
 627          * @param       $subValue       Value of the sub action
 628          * @return      void
 629          * @throws      HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found
 630          * @todo        Add checking if sub option is already added
 631          */
 632         public function addSelectSubOption ($subName, $subValue) {
 633                 // Is there a sub group (shall be a selection box!)
 634                 if ($this->ifSubGroupOpenedPreviously() === FALSE) {
 635                         // Then throw an exception here
 636                         throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
 637                 } // END - if
 638
 639                 // Render the content
 640                 $content = sprintf("<option value=\"invalid\" class=\"suboption suboption_%s\" disabled=\"disabled\">%s</option>\n",
 641                         $subName,
 642                         $subValue
 643                 );
 644
 645                 // Add the content to the previously opened sub group
 646                 $this->addContentToPreviousGroup($content);
 647         }
 648
 649         /**
 650          * Adds a selectable option to a previously added selection box. This method
 651          * does *not* validate if there is already a sub option added with the same
 652          * name. We need to finish this here!
 653          *
 654          * @param       $optionName     Name of the sub action
 655          * @param       $optionValue    Value of the sub action
 656          * @return      void
 657          * @throws      HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found
 658          * @todo        Add checking if sub option is already added
 659          */
 660         public function addSelectOption ($optionName, $optionValue) {
 661                 // Is there a sub group (shall be a selection box!)
 662                 if ($this->ifSubGroupOpenedPreviously() === FALSE) {
 663                         // Then throw an exception here
 664                         throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
 665                 } // END - if
 666
 667                 // Render the content
 668                 $content = sprintf("<option value=\"%s\" class=\"option option_%s\">%s</option>\n",
 669                         $optionName,
 670                         $optionName,
 671                         $optionValue
 672                 );
 673
 674                 // Add the content to the previously opened sub group
 675                 $this->addContentToPreviousGroup($content);
 676         }
 677
 678         /**
 679          * Adds a pre-configured CAPTCHA
 680          *
 681          * @return      void
 682          */
 683         public function addCaptcha () {
 684                 // Init instance
 685                 $extraInstance = NULL;
 686
 687                 try {
 688                         // Get last executed pre filter
 689                         $extraInstance = Registry::getRegistry()->getInstance('extra');
 690                 } catch (NullPointerException $e) {
 691                         // Instance in registry is not set (NULL)
 692                         // @TODO We need to log this later
 693                 }
 694
 695                 // Get a configured instance
 696                 $captchaInstance = ObjectFactory::createObjectByConfiguredName($this->getFormName() . '_captcha_class', array($this, $extraInstance));
 697
 698                 // Initiate the CAPTCHA
 699                 $captchaInstance->initiateCaptcha();
 700
 701                 // Render the CAPTCHA code
 702                 $captchaInstance->renderCode();
 703
 704                 // Get the content and add it to the helper
 705                 $this->addContentToPreviousGroup($captchaInstance->renderContent());
 706         }
 707
 708         /**
 709          * Enables/disables the form tag usage
 710          *
 711          * @param       $formEnabled    Whether form is enabled or disabled
 712          * @return      void
 713          */
 714         public final function enableForm ($formEnabled = TRUE) {
 715                 $this->formEnabled = (bool) $formEnabled;
 716         }
 717
 718         /**
 719          * Setter for form name
 720          *
 721          * @param       $formName       Name of this form
 722          * @return      void
 723          */
 724         public final function setFormName ($formName) {
 725                 $this->formName = (string) $formName;
 726         }
 727
 728         /**
 729          * Getter for form name
 730          *
 731          * @return      $formName       Name of this form
 732          */
 733         public final function getFormName () {
 734                 return $this->formName;
 735         }
 736
 737         /**
 738          * Checks whether the registration requires a valid email address
 739          *
 740          * @return      $required       Whether the email address is required
 741          */
 742         public function ifRegisterRequiresEmailVerification () {
 743                 $required = ($this->getConfigInstance()->getConfigEntry('register_requires_email') == 'Y');
 744                 return $required;
 745         }
 746
 747         /**
 748          * Checks whether profile data shall be asked
 749          *
 750          * @return      $required       Whether profile data shall be asked
 751          */
 752         public function ifRegisterIncludesProfile () {
 753                 $required = ($this->getConfigInstance()->getConfigEntry('register_includes_profile') == 'Y');
 754                 return $required;
 755         }
 756
 757         /**
 758          * Checks whether this form is secured by a CAPTCHA
 759          *
 760          * @return      $isSecured      Whether this form is secured by a CAPTCHA
 761          */
 762         public function ifFormSecuredWithCaptcha () {
 763                 $isSecured = ($this->getConfigInstance()->getConfigEntry($this->getFormName() . '_captcha_secured') == 'Y');
 764                 return $isSecured;
 765         }
 766
 767         /**
 768          * Checks whether personal data shall be asked
 769          *
 770          * @return      $required       Whether personal data shall be asked
 771          */
 772         public function ifRegisterIncludesPersonaData () {
 773                 $required = ($this->getConfigInstance()->getConfigEntry('register_personal_data') == 'Y');
 774                 return $required;
 775         }
 776
 777         /**
 778          * Checks whether for birthday shall be asked
 779          *
 780          * @return      $required       Whether birthday shall be asked
 781          */
 782         public function ifProfileIncludesBirthDay () {
 783                 $required = ($this->getConfigInstance()->getConfigEntry('profile_includes_birthday') == 'Y');
 784                 return $required;
 785         }
 786
 787         /**
 788          * Checks whether email addresses can only be once used
 789          *
 790          * @return      $isUnique
 791          */
 792         public function ifEmailMustBeUnique () {
 793                 $isUnique = ($this->getConfigInstance()->getConfigEntry('register_email_unique') == 'Y');
 794                 return $isUnique;
 795         }
 796
 797         /**
 798          * Checks whether the specified chat protocol is enabled in this form
 799          *
 800          * @return      $required       Whether the specified chat protocol is enabled
 801          */
 802         public function ifChatEnabled ($chatProtocol) {
 803                 $required = ($this->getConfigInstance()->getConfigEntry('chat_enabled_' . $chatProtocol) == 'Y');
 804                 return $required;
 805         }
 806
 807         /**
 808          * Checks whether login is enabled or disabled
 809          *
 810          * @return      $isEnabled      Whether the login is enabled or disabled
 811          */
 812         public function ifLoginIsEnabled () {
 813                 $isEnabled = ($this->getConfigInstance()->getConfigEntry('login_enabled') == 'Y');
 814                 return $isEnabled;
 815         }
 816
 817         /**
 818          * Checks whether login shall be done by username
 819          *
 820          * @return      $isEnabled      Whether the login shall be done by username
 821          */
 822         public function ifLoginWithUsername () {
 823                 $isEnabled = ($this->getConfigInstance()->getConfigEntry('login_type') == "username");
 824                 return $isEnabled;
 825         }
 826
 827         /**
 828          * Checks whether login shall be done by email
 829          *
 830          * @return      $isEnabled      Whether the login shall be done by email
 831          */
 832         public function ifLoginWithEmail () {
 833                 $isEnabled = ($this->getConfigInstance()->getConfigEntry('login_type') == "email");
 834                 return $isEnabled;
 835         }
 836
 837         /**
 838          * Checks whether guest login is allowed
 839          *
 840          * @return      $isAllowed      Whether guest login is allowed
 841          */
 842         public function ifGuestLoginAllowed () {
 843                 $isAllowed = ($this->getConfigInstance()->getConfigEntry('guest_login_allowed') == 'Y');
 844                 return $isAllowed;
 845         }
 846
 847         /**
 848          * Checks whether the email address change must be confirmed
 849          *
 850          * @return      $requireConfirm         Whether email change must be confirmed
 851          */
 852         public function ifEmailChangeRequireConfirmation () {
 853                 $requireConfirm = ($this->getConfigInstance()->getConfigEntry('email_change_confirmation') == 'Y');
 854                 return $requireConfirm;
 855         }
 856
 857         /**
 858          * Checks whether the rules has been updated
 859          *
 860          * @return      $rulesUpdated   Whether rules has been updated
 861          * @todo        Implement check if rules have been changed
 862          */
 863         public function ifRulesHaveChanged () {
 864                 return FALSE;
 865         }
 866
 867         /**
 868          * Checks whether email change is allowed
 869          *
 870          * @return      $emailChange    Whether changing email address is allowed
 871          */
 872         public function ifEmailChangeAllowed () {
 873                 $emailChange = ($this->getConfigInstance()->getConfigEntry('email_change_allowed') == 'Y');
 874                 return $emailChange;
 875         }
 876
 877         /**
 878          * Checks whether the user account is unconfirmed
 879          *
 880          * @return      $isUnconfirmed  Whether the user account is unconfirmed
 881          */
 882         public function ifUserAccountUnconfirmed () {
 883                 $isUnconfirmed = ($this->getValueField(UserDatabaseWrapper::DB_COLUMN_USER_STATUS) === $this->getConfigInstance()->getConfigEntry('user_status_unconfirmed'));
 884                 return $isUnconfirmed;
 885         }
 886
 887         /**
 888          * Checks whether the user account is locked
 889          *
 890          * @return      $isUnconfirmed  Whether the user account is locked
 891          */
 892         public function ifUserAccountLocked () {
 893                 $isUnconfirmed = ($this->getValueField(UserDatabaseWrapper::DB_COLUMN_USER_STATUS) === $this->getConfigInstance()->getConfigEntry('user_status_locked'));
 894                 return $isUnconfirmed;
 895         }
 896
 897         /**
 898          * Checks whether the user account is a guest
 899          *
 900          * @return      $isUnconfirmed  Whether the user account is a guest
 901          */
 902         public function ifUserAccountGuest () {
 903                 $isUnconfirmed = ($this->getValueField(UserDatabaseWrapper::DB_COLUMN_USER_STATUS) === $this->getConfigInstance()->getConfigEntry('user_status_guest'));
 904                 return $isUnconfirmed;
 905         }
 906
 907         /**
 908          * Checks whether the refill page is active which should be not the default
 909          * on non-web applications.
 910          *
 911          * @return      $refillActive   Whether the refill page is active
 912          */
 913         public function ifRefillPageActive () {
 914                 $refillActive = ($this->getConfigInstance()->getConfigEntry('refill_page_active') == 'Y');
 915                 return $refillActive;
 916         }
 917
 918         /**
 919          * Flushs the content out (not yet secured against open forms, etc.!) or
 920          * close the form automatically
 921          *
 922          * @return      void
 923          * @throws      FormOpenedException             If the form is still open
 924          */
 925         public function flushContent () {
 926                 // Is the form still open?
 927                 if (($this->formOpened === TRUE) && ($this->formEnabled === TRUE)) {
 928                         // Close the form automatically
 929                         $this->addFormTag();
 930                 } elseif ($this->formEnabled === FALSE) {
 931                         if ($this->ifSubGroupOpenedPreviously()) {
 932                                 // Close sub group
 933                                 $this->addFormSubGroup();
 934                         } elseif ($this->ifGroupOpenedPreviously()) {
 935                                 // Close group
 936                                 $this->addFormGroup();
 937                         }
 938                 }
 939
 940                 // Send content to template engine
 941                 //* DEBUG: */ print __METHOD__.": form=".$this->getFormName().", size=".strlen($this->renderContent())."<br />\n";
 942                 $this->getTemplateInstance()->assignVariable($this->getFormName(), $this->renderContent());
 943         }
 944
 945 }