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