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

   1 <?php
   2 // Own namespace
   3 namespace CoreFramework\Helper;
   4
   5 // Import framework stuff
   6 use CoreFramework\Factory\ObjectFactory;
   7 use CoreFramework\Registry\Generic\Registry;
   8 use CoreFramework\Template\CompileableTemplate;
   9
  10 /**
  11  * A helper for constructing web forms
  12  *
  13  * @author              Roland Haeder <webmaster@shipsimu.org>
  14  * @version             0.0.0
  15  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
  16  * @license             GNU GPL 3.0 or any newer version
  17  * @link                http://www.shipsimu.org
  18  *
  19  * This program is free software: you can redistribute it and/or modify
  20  * it under the terms of the GNU General Public License as published by
  21  * the Free Software Foundation, either version 3 of the License, or
  22  * (at your option) any later version.
  23  *
  24  * This program is distributed in the hope that it will be useful,
  25  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  26  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  27  * GNU General Public License for more details.
  28  *
  29  * You should have received a copy of the GNU General Public License
  30  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  31  */
  32 class HtmlFormHelper extends BaseHtmlHelper implements HelpableTemplate {
  33         /**
  34          * Whether the form tag is opened (keep at FALSE or else your forms will
  35          * never work!)
  36          */
  37         private $formOpened = FALSE;
  38
  39         /**
  40          * Name of the form
  41          */
  42         private $formName = '';
  43
  44         /**
  45          * Whether form tag is enabled (default: TRUE)
  46          */
  47         private $formEnabled = TRUE;
  48
  49         // Class Constants
  50         const EXCEPTION_FORM_NAME_INVALID       = 0x120;
  51         const EXCEPTION_CLOSED_FORM             = 0x121;
  52         const EXCEPTION_OPENED_FORM             = 0x122;
  53         const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x123;
  54
  55         /**
  56          * Protected constructor
  57          *
  58          * @return      void
  59          */
  60         protected function __construct () {
  61                 // Call parent constructor
  62                 parent::__construct(__CLASS__);
  63         }
  64
  65         /**
  66          * Creates the helper class with the given template engine instance and form name
  67          *
  68          * @param       $templateInstance       An instance of a valid template engine
  69          * @param       $formName                       Name of the form
  70          * @param       $formId                         Value for 'id' attribute (default: $formName)
  71          * @param       $withForm                       Whether include the form tag
  72          * @return      $helperInstance         A preparedf instance of this helper
  73          */
  74         public static final function createHtmlFormHelper (CompileableTemplate $templateInstance, $formName, $formId = FALSE, $withForm = TRUE) {
  75                 // Get new instance
  76                 $helperInstance = new HtmlFormHelper();
  77
  78                 // Set template instance
  79                 $helperInstance->setTemplateInstance($templateInstance);
  80
  81                 // Is the form id not set?
  82                 if ($formId === FALSE) {
  83                         // Use form id from form name
  84                         $formId = $formName;
  85                 } // END - if
  86
  87                 // Set form name
  88                 $helperInstance->setFormName($formName);
  89
  90                 // A form-less field may say 'FALSE' here...
  91                 if ($withForm === TRUE) {
  92                         // Create the form
  93                         $helperInstance->addFormTag($formName, $formId);
  94                 } else {
  95                         // Disable form
  96                         $helperInstance->enableForm(FALSE);
  97                 }
  98
  99                 // Return the prepared instance
 100                 return $helperInstance;
 101         }
 102
 103         /**
 104          * Add the form tag or close it an already opened form tag
 105          *
 106          * @param       $formName       Name of the form (default: FALSE)
 107          * @param       $formId         Id of the form (attribute 'id'; default: FALSE)
 108          * @return      void
 109          * @throws      InvalidFormNameException        If the form name is invalid ( = FALSE)
 110          * @todo        Add some unique PIN here to bypass problems with some browser and/or extensions
 111          */
 112         public function addFormTag ($formName = FALSE, $formId = FALSE) {
 113                 // When the form is not yet opened at least form name must be valid
 114                 if (($this->formOpened === FALSE) && ($formName === FALSE)) {
 115                         // Thrown an exception
 116                         throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
 117                 } // END - if
 118
 119                 // Close the form is default
 120                 $formContent = '</form>';
 121
 122                 // Check whether we shall open or close the form
 123                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 124                         // Add HTML code
 125                         $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
 126                                 $formName,
 127                                 $this->getConfigInstance()->getConfigEntry('base_url'),
 128                                 $this->getConfigInstance()->getConfigEntry('form_action'),
 129                                 $this->getConfigInstance()->getConfigEntry('form_method'),
 130                                 $this->getConfigInstance()->getConfigEntry('form_target')
 131                         );
 132
 133                         // Add form id as well
 134                         $formContent .= sprintf(" id=\"%s_form\"",
 135                                 $formId
 136                         );
 137
 138                         // Add close bracket
 139                         $formContent .= '>';
 140
 141                         // Open the form and remeber the form name
 142                         $this->formOpened = TRUE;
 143
 144                         // Add it to the content
 145                         $this->addHeaderContent($formContent);
 146                 } else {
 147                         // Add the hidden field required to identify safely this form
 148                         $this->addInputHiddenField('form', $this->getFormName());
 149
 150                         // Is a group open?
 151                         if ($this->ifGroupOpenedPreviously()) {
 152                                 // Then automatically close it here
 153                                 $this->addFormGroup();
 154                         } // END - if
 155
 156                         // Simply close it
 157                         $this->formOpened = FALSE;
 158
 159                         // Add it to the content
 160                         $this->addFooterContent($formContent);
 161                 }
 162         }
 163
 164         /**
 165          * Add a text input tag to the form or throw an exception if it is not yet
 166          * opened. The field's name will be set as id.
 167          *
 168          * @param       $fieldName              Input field name
 169          * @param       $fieldValue             Input default value (default: empty)
 170          * @return      void
 171          * @throws      FormClosedException             If the form is not yet opened
 172          */
 173         public function addInputTextField ($fieldName, $fieldValue = '') {
 174                 // Is the form opened?
 175                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 176                         // Throw an exception
 177                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 178                 } // END - if
 179
 180                 // Generate the content
 181                 $inputContent = sprintf("<input type=\"text\" class=\"textfield %s_field\" name=\"%s\" value=\"%s\" />",
 182                         $fieldName,
 183                         $fieldName,
 184                         $fieldValue
 185                 );
 186
 187                 // And add it maybe with a 'li' tag
 188                 $this->addContentToPreviousGroup($inputContent);
 189         }
 190
 191         /**
 192          * Add a text input tag to the form with pre-loaded default value
 193          *
 194          * @param       $fieldName      Input field name
 195          * @return      void
 196          */
 197         public function addInputTextFieldWithDefault ($fieldName) {
 198                 // Get the value from instance
 199                 $fieldValue = $this->getValueField($fieldName);
 200                 //* DEBUG: */ print __METHOD__.':'.$fieldName.'='.$fieldValue."<br />\n";
 201
 202                 // Add the text field
 203                 $this->addInputTextField($fieldName, $fieldValue);
 204         }
 205
 206         /**
 207          * Add a password input tag to the form or throw an exception if it is not
 208          * yet opened. The field's name will be set as id.
 209          *
 210          * @param       $fieldName              Input field name
 211          * @param       $fieldValue             Input default value (default: empty)
 212          * @return      void
 213          * @throws      FormClosedException             If the form is not yet opened
 214          */
 215         public function addInputPasswordField ($fieldName, $fieldValue = '') {
 216                 // Is the form opened?
 217                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 218                         // Throw an exception
 219                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 220                 } // END - if
 221
 222                 // Generate the content
 223                 $inputContent = sprintf("<input type=\"password\" class=\"password %s_field\" name=\"%s\" value=\"%s\" />",
 224                         $fieldName,
 225                         $fieldName,
 226                         $fieldValue
 227                 );
 228
 229                 // And add it
 230                 $this->addContentToPreviousGroup($inputContent);
 231         }
 232
 233         /**
 234          * Add a hidden input tag to the form or throw an exception if it is not
 235          * yet opened. The field's name will be set as id.
 236          *
 237          * @param       $fieldName              Input field name
 238          * @param       $fieldValue             Input default value (default: empty)
 239          * @return      void
 240          * @throws      FormClosedException             If the form is not yet opened
 241          */
 242         public function addInputHiddenField ($fieldName, $fieldValue = '') {
 243                 // Is the form opened?
 244                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 245                         // Throw an exception
 246                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 247                 } // END - if
 248
 249                 // Generate the content
 250                 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
 251                         $fieldName,
 252                         $fieldValue
 253                 );
 254
 255                 // And add it
 256                 $this->addContentToPreviousGroup($inputContent);
 257         }
 258
 259         /**
 260          * Add a hidden input tag to the form with pre-loaded default value
 261          *
 262          * @param       $fieldName      Input field name
 263          * @return      void
 264          */
 265         public function addInputHiddenFieldWithDefault ($fieldName) {
 266                 // Get the value from instance
 267                 $fieldValue = $this->getValueField($fieldName);
 268                 //* DEBUG: */ print __METHOD__.':'.$fieldName.'='.$fieldValue."<br />\n";
 269
 270                 // Add the text field
 271                 $this->addInputHiddenField($fieldName, $fieldValue);
 272         }
 273
 274         /**
 275          * Add a hidden input tag to the form with configuration value
 276          *
 277          * @param       $fieldName      Input field name
 278          * @param       $prefix         Prefix for configuration without trailing _
 279          * @return      void
 280          */
 281         public function addInputHiddenConfiguredField ($fieldName, $prefix) {
 282                 // Get the value from instance
 283                 $fieldValue = $this->getConfigInstance()->getConfigEntry("{$prefix}_{$fieldName}");
 284                 //* DEBUG: */ print __METHOD__.':'.$fieldName.'='.$fieldValue."<br />\n";
 285
 286                 // Add the text field
 287                 $this->addInputHiddenField($fieldName, $fieldValue);
 288         }
 289
 290         /**
 291          * Add a checkbox input tag to the form or throw an exception if it is not
 292          * yet opened. The field's name will be set as id.
 293          *
 294          * @param       $fieldName              Input field name
 295          * @param       $fieldChecked   Whether the field is checked (defaut: checked)
 296          * @return      void
 297          * @throws      FormClosedException             If the form is not yet opened
 298          */
 299         public function addInputCheckboxField ($fieldName, $fieldChecked = TRUE) {
 300                 // Is the form opened?
 301                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 302                         // Throw an exception
 303                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
 304                 } // END - if
 305
 306                 // Set whether the check box is checked...
 307                 $checked = " checked=\"checked\"";
 308                 if ($fieldChecked === FALSE) $checked = ' ';
 309
 310                 // Generate the content
 311                 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox %s_field\" value=\"1\"%s/>",
 312                         $fieldName,
 313                         $fieldName,
 314                         $checked
 315                 );
 316
 317                 // And add it
 318                 $this->addContentToPreviousGroup($inputContent);
 319         }
 320
 321         /**
 322          * Add a reset input tag to the form or throw an exception if it is not
 323          * yet opened. The field's name will be set as id.
 324          *
 325          * @param       $buttonText             Text displayed on the button
 326          * @return      void
 327          * @throws      FormClosedException             If the form is not yet opened
 328          */
 329         public function addInputResetButton ($buttonText) {
 330                 // Is the form opened?
 331                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 332                         // Throw an exception
 333                         throw new FormClosedException (array($this, 'reset'), self::EXCEPTION_CLOSED_FORM);
 334                 } // END - if
 335
 336                 // Generate the content
 337                 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
 338                         $this->getFormName(),
 339                         $buttonText
 340                 );
 341
 342                 // And add it
 343                 $this->addContentToPreviousGroup($inputContent);
 344         }
 345
 346         /**
 347          * Add a reset input tag to the form or throw an exception if it is not
 348          * yet opened. The field's name will be set as id.
 349          *
 350          * @param       $buttonText             Text displayed on the button
 351          * @return      void
 352          * @throws      FormClosedException             If the form is not yet opened
 353          */
 354         public function addInputSubmitButton ($buttonText) {
 355                 // Is the form opened?
 356                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 357                         // Throw an exception
 358                         throw new FormClosedException (array($this, 'submit'), self::EXCEPTION_CLOSED_FORM);
 359                 } // END - if
 360
 361                 // Generate the content
 362                 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
 363                         $this->getFormName(),
 364                         $this->getFormName(),
 365                         $buttonText
 366                 );
 367
 368                 // And add it
 369                 $this->addContentToPreviousGroup($inputContent);
 370         }
 371
 372         /**
 373          * Add a form group or close an already opened and open a new one
 374          *
 375          * @param       $groupId        Name of the group or last opened if empty
 376          * @param       $groupText      Text including HTML to show above this group
 377          * @return      void
 378          * @throws      FormClosedException             If no form has been opened before
 379          * @throws      EmptyVariableException  If $groupId is not set
 380          */
 381         public function addFormGroup ($groupId = '', $groupText = '') {
 382                 // Is a form opened?
 383                 if (($this->formOpened === FALSE) && ($this->formEnabled === TRUE)) {
 384                         // Throw exception here
 385                         throw new FormClosedException(array($this, $groupId), self::EXCEPTION_CLOSED_FORM);
 386                 } // END - if
 387
 388                 // At least the group name should be set
 389                 if ((empty($groupId)) && ($this->ifGroupOpenedPreviously() === FALSE)) {
 390                         // Throw exception here
 391                         throw new EmptyVariableException(array($this, 'groupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 392                 } elseif (empty($groupId)) {
 393                         // Close the last opened
 394                         $groupId = $this->getPreviousGroupId();
 395                 }
 396
 397                 // Same group to open?
 398                 if (($this->ifGroupOpenedPreviously() === FALSE) && ($groupId === $this->getPreviousGroupId())) {
 399                         // Abort here silently
 400                         return FALSE;
 401                 } // END - if
 402
 403                 // Initialize content with closing div by default
 404                 $content = "    </div>\n</div><!-- Group - CLOSE //-->";
 405
 406                 // Is this group opened?
 407                 if ($this->ifGroupOpenedPreviously() === FALSE) {
 408                         // Begin the div/span blocks
 409                         $content = sprintf("<!-- Group %s - OPEN //-->
 410 <div class=\"group_box\" id=\"%s_group_box\">
 411         <span class=\"group_text\" id=\"%s_group_text\">
 412                 %s
 413         </span>
 414         <div class=\"group_field\" id=\"%s_group_field\">",
 415                                 $groupId,
 416                                 $groupId,
 417                                 $groupId,
 418                                 $groupText,
 419                                 $groupId
 420                         );
 421
 422                         // Switch the state
 423                         $this->openGroupByIdContent($groupId, $content, "div");
 424                 } else {
 425                         // Is a sub group opened?
 426                         if ($this->ifSubGroupOpenedPreviously()) {
 427                                 // Close it here
 428                                 $this->addFormSubGroup();
 429                         } // END - if
 430
 431                         // Get previous group id
 432                         $prevGroupId = $this->getPreviousGroupId();
 433
 434                         // Switch the state
 435                         $this->closePreviousGroupByContent($content);
 436
 437                         // All call it again if group name is not empty
 438                         if ((!empty($groupId)) && ($groupId != $prevGroupId)) {
 439                                 //* DEBUG: */ echo $groupId.'/'.$prevGroupId."<br />\n";
 440                                 $this->addFormGroup($groupId, $groupText);
 441                         } // END - if
 442                 }
 443         }
 444
 445         /**
 446          * Add a form sub group or close an already opened and open a new one or
 447          * throws an exception if no group has been opened before or if sub group
 448          * name is empty.
 449          *
 450          * @param       $subGroupId             Name of the group or last opened if empty
 451          * @param       $subGroupText   Text including HTML to show above this group
 452          * @return      void
 453          * @throws      FormFormClosedException         If no group has been opened before
 454          * @throws      EmptyVariableException          If $subGroupId is not set
 455          */
 456         public function addFormSubGroup ($subGroupId = '', $subGroupText = '') {
 457                 // Is a group opened?
 458                 if ($this->ifGroupOpenedPreviously() === FALSE) {
 459                         // Throw exception here
 460                         throw new FormFormClosedException(array($this, $subGroupId), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
 461                 } // END - if
 462
 463                 // At least the sub group name should be set
 464                 if ((empty($subGroupId)) && ($this->ifSubGroupOpenedPreviously() === FALSE)) {
 465                         // Throw exception here
 466                         throw new EmptyVariableException(array($this, 'subGroupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 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 = Registry::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 }