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