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

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