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