2f3502c9e75632ca396cb00c2dbee2e2052b7295
[shipsimu.git] / inc / classes / main / helper / web / forms / class_WebFormHelper.php
1 <?php
2 /**
3  * A helper for constructing web forms
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, this is free software
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.ship-simu.org
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 3 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program. If not, see <http://www.gnu.org/licenses/>.
23  */
24 class WebFormHelper extends BaseWebHelper implements HelpableTemplate {
25         /**
26          * Wether the form tag is opened (keep at false or else your forms will
27          * never work!)
28          */
29         private $formOpened = false;
30
31         /**
32          * Name of the form
33          */
34         private $formName = "";
35
36         /**
37          * Wether form tag is enabled (default: true)
38          */
39         private $formEnabled = true;
40
41         // Class Constants
42         const EXCEPTION_FORM_NAME_INVALID       = 0x120;
43         const EXCEPTION_CLOSED_FORM             = 0x121;
44         const EXCEPTION_OPENED_FORM             = 0x122;
45         const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x123;
46
47         /**
48          * Protected constructor
49          *
50          * @return      void
51          */
52         protected function __construct () {
53                 // Call parent constructor
54                 parent::__construct(__CLASS__);
55         }
56
57         /**
58          * Creates the helper class with the given template engine instance and form name
59          *
60          * @param       $templateInstance       An instance of a valid template engine
61          * @param       $formName                       Name of the form
62          * @param       $formId                         Value for "id" attribute (default: $formName)
63          * @param       $withForm                       Wether include the form tag
64          * @return      $helperInstance         A preparedf instance of this helper
65          */
66         public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false, $withForm = true) {
67                 // Get new instance
68                 $helperInstance = new WebFormHelper();
69
70                 // Set template instance
71                 $helperInstance->setTemplateInstance($templateInstance);
72
73                 // Is the form id not set?
74                 if ($formId === false) {
75                         // Use form id from form name
76                         $formId = $formName;
77                 } // END - if
78
79                 // Set form name
80                 $helperInstance->setFormName($formName);
81
82                 // A form-less field may say "false" here...
83                 if ($withForm === true) {
84                         // Create the form
85                         $helperInstance->addFormTag($formName, $formId);
86                 } else {
87                         // Disable form
88                         $helperInstance->enableForm(false);
89                 }
90
91                 // Return the prepared instance
92                 return $helperInstance;
93         }
94
95         /**
96          * Add the form tag or close it an already opened form tag
97          *
98          * @param       $formName       Name of the form (default: false)
99          * @param       $formId         Id of the form (attribute "id"; default: false)
100          * @return      void
101          * @throws      InvalidFormNameException        If the form name is invalid (=false)
102          * @todo        Add some unique PIN here to bypass problems with some browser and/or extensions
103          */
104         public function addFormTag ($formName = false, $formId = false) {
105                 // When the form is not yet opened at least form name must be valid
106                 if (($this->formOpened === false) && ($formName === false)) {
107                         // Thrown an exception
108                         throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
109                 } // END - if
110
111                 // Close the form is default
112                 $formContent = "</form>";
113
114                 // Check wether we shall open or close the form
115                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
116                         // Add HTML code
117                         $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
118                                 $formName,
119                                 $this->getConfigInstance()->readConfig('base_url'),
120                                 $this->getConfigInstance()->readConfig('form_action'),
121                                 $this->getConfigInstance()->readConfig('form_method'),
122                                 $this->getConfigInstance()->readConfig('form_target')
123                         );
124
125                         // Add form id as well
126                         $formContent .= sprintf(" id=\"%s_form\"",
127                                 $formId
128                         );
129
130                         // Add close bracket
131                         $formContent .= ">";
132
133                         // Open the form and remeber the form name
134                         $this->formOpened = true;
135
136                         // Add it to the content
137                         $this->addHeaderContent($formContent);
138                 } else {
139                         // Add the hidden field required to identify safely this form
140                         $this->addInputHiddenField('form', $this->getFormName());
141
142                         // Is a group open?
143                         if ($this->ifGroupOpenedPreviously()) {
144                                 // Then automatically close it here
145                                 $this->addFormGroup();
146                         } // END - if
147
148                         // Simply close it
149                         $this->formOpened = false;
150
151                         // Add it to the content
152                         $this->addFooterContent($formContent);
153                 }
154         }
155
156         /**
157          * Add a text input tag to the form or throw an exception if it is not yet
158          * opened. The field's name will be set as id.
159          *
160          * @param       $fieldName              Input field name
161          * @param       $fieldValue             Input default value (default: empty)
162          * @return      void
163          * @throws      FormClosedException             If the form is not yet opened
164          */
165         public function addInputTextField ($fieldName, $fieldValue = "") {
166                 // Is the form opened?
167                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
168                         // Throw an exception
169                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
170                 } // END - if
171
172                 // Generate the content
173                 $inputContent = sprintf("<input type=\"text\" class=\"textfield %s_field\" name=\"%s\" value=\"%s\" />",
174                         $fieldName,
175                         $fieldName,
176                         $fieldValue
177                 );
178
179                 // And add it maybe with a "li" tag
180                 $this->addContentToPreviousGroup($inputContent);
181         }
182
183         /**
184          * Add a text input tag to the form with pre-loaded default value
185          *
186          * @param       $fieldName      Input field name
187          * @return      void
188          */
189         public function addInputTextFieldWithDefault ($fieldName) {
190                 // Get the value from instance
191                 $fieldValue = $this->getValueField($fieldName);
192                 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
193
194                 // Add the text field
195                 $this->addInputTextField($fieldName, $fieldValue);
196         }
197
198         /**
199          * Add a password input tag to the form or throw an exception if it is not
200          * yet opened. The field's name will be set as id.
201          *
202          * @param       $fieldName              Input field name
203          * @param       $fieldValue             Input default value (default: empty)
204          * @return      void
205          * @throws      FormClosedException             If the form is not yet opened
206          */
207         public function addInputPasswordField ($fieldName, $fieldValue = "") {
208                 // Is the form opened?
209                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
210                         // Throw an exception
211                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
212                 } // END - if
213
214                 // Generate the content
215                 $inputContent = sprintf("<input type=\"password\" class=\"password %s_field\" name=\"%s\" value=\"%s\" />",
216                         $fieldName,
217                         $fieldName,
218                         $fieldValue
219                 );
220
221                 // And add it
222                 $this->addContentToPreviousGroup($inputContent);
223         }
224
225         /**
226          * Add a hidden input tag to the form or throw an exception if it is not
227          * yet opened. The field's name will be set as id.
228          *
229          * @param       $fieldName              Input field name
230          * @param       $fieldValue             Input default value (default: empty)
231          * @return      void
232          * @throws      FormClosedException             If the form is not yet opened
233          */
234         public function addInputHiddenField ($fieldName, $fieldValue = "") {
235                 // Is the form opened?
236                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
237                         // Throw an exception
238                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
239                 } // END - if
240
241                 // Generate the content
242                 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
243                         $fieldName,
244                         $fieldValue
245                 );
246
247                 // And add it
248                 $this->addContentToPreviousGroup($inputContent);
249         }
250
251         /**
252          * Add a hidden input tag to the form with pre-loaded default value
253          *
254          * @param       $fieldName      Input field name
255          * @return      void
256          */
257         public function addInputHiddenFieldWithDefault ($fieldName) {
258                 // Get the value from instance
259                 $fieldValue = $this->getValueField($fieldName);
260                 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
261
262                 // Add the text field
263                 $this->addInputHiddenField($fieldName, $fieldValue);
264         }
265
266         /**
267          * Add a hidden input tag to the form with configuration value
268          *
269          * @param       $fieldName      Input field name
270          * @param       $prefix         Prefix for configuration without trailing _
271          * @return      void
272          */
273         public function addInputHiddenConfiguredField ($fieldName, $prefix) {
274                 // Get the value from instance
275                 $fieldValue = $this->getConfigInstance()->readConfig("{$prefix}_{$fieldName}");
276                 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
277
278                 // Add the text field
279                 $this->addInputHiddenField($fieldName, $fieldValue);
280         }
281
282         /**
283          * Add a checkbox input tag to the form or throw an exception if it is not
284          * yet opened. The field's name will be set as id.
285          *
286          * @param       $fieldName              Input field name
287          * @param       $fieldChecked   Wether the field is checked (defaut: checked)
288          * @return      void
289          * @throws      FormClosedException             If the form is not yet opened
290          */
291         public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
292                 // Is the form opened?
293                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
294                         // Throw an exception
295                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
296                 } // END - if
297
298                 // Set wether the check box is checked...
299                 $checked = " checked=\"checked\"";
300                 if ($fieldChecked === false) $checked = " ";
301
302                 // Generate the content
303                 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox %s_field\" value=\"1\"%s/>",
304                         $fieldName,
305                         $fieldName,
306                         $checked
307                 );
308
309                 // And add it
310                 $this->addContentToPreviousGroup($inputContent);
311         }
312
313         /**
314          * Add a reset input tag to the form or throw an exception if it is not
315          * yet opened. The field's name will be set as id.
316          *
317          * @param       $buttonText             Text displayed on the button
318          * @return      void
319          * @throws      FormClosedException             If the form is not yet opened
320          */
321         public function addInputResetButton ($buttonText) {
322                 // Is the form opened?
323                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
324                         // Throw an exception
325                         throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
326                 } // END - if
327
328                 // Generate the content
329                 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
330                         $this->getFormName(),
331                         $buttonText
332                 );
333
334                 // And add it
335                 $this->addContentToPreviousGroup($inputContent);
336         }
337
338         /**
339          * Add a reset input tag to the form or throw an exception if it is not
340          * yet opened. The field's name will be set as id.
341          *
342          * @param       $buttonText             Text displayed on the button
343          * @return      void
344          * @throws      FormClosedException             If the form is not yet opened
345          */
346         public function addInputSubmitButton ($buttonText) {
347                 // Is the form opened?
348                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
349                         // Throw an exception
350                         throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
351                 } // END - if
352
353                 // Generate the content
354                 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
355                         $this->getFormName(),
356                         $this->getFormName(),
357                         $buttonText
358                 );
359
360                 // And add it
361                 $this->addContentToPreviousGroup($inputContent);
362         }
363
364         /**
365          * Add a form group or close an already opened and open a new one
366          *
367          * @param       $groupId        Name of the group or last opened if empty
368          * @param       $groupText      Text including HTML to show above this group
369          * @return      void
370          * @throws      FormClosedException             If no form has been opened before
371          * @throws      EmptyVariableException  If $groupId is not set
372          */
373         public function addFormGroup ($groupId = "", $groupText = "") {
374                 // Is a form opened?
375                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
376                         // Throw exception here
377                         throw new FormClosedException(array($this, $groupId), self::EXCEPTION_CLOSED_FORM);
378                 } // END - if
379
380                 // At least the group name should be set
381                 if ((empty($groupId)) && (!$this->ifGroupOpenedPreviously())) {
382                         // Throw exception here
383                         throw new EmptyVariableException(array($this, 'groupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
384                 } elseif (empty($groupId)) {
385                         // Close the last opened
386                         $groupId = $this->getPreviousGroupId();
387                 }
388
389                 // Same group to open?
390                 if ((!$this->ifGroupOpenedPreviously()) && ($groupId == $this->getPreviousGroupId())) {
391                         // Abort here silently
392                         return false;
393                 } // END - if
394
395                 // Initialize content with closing div by default
396                 $content = "    </div>\n</div><!-- Group - CLOSE //-->";
397
398                 // Is this group opened?
399                 if (!$this->ifGroupOpenedPreviously()) {
400                         // Begin the div/span blocks
401                         $content = sprintf("<!-- Group %s - OPEN //-->
402 <div class=\"group_box\" id=\"%s_group_box\">
403         <span class=\"group_text\" id=\"%s_group_text\">
404                 %s
405         </span>
406         <div class=\"group_field\" id=\"%s_group_field\">",
407                                 $groupId,
408                                 $groupId,
409                                 $groupId,
410                                 $groupText,
411                                 $groupId
412                         );
413
414                         // Switch the state
415                         $this->openGroupByIdContent($groupId, $content);
416                 } else {
417                         // Is a sub group opened?
418                         if ($this->ifSubGroupOpenedPreviously()) {
419                                 // Close it here
420                                 $this->addFormSubGroup();
421                         } // END - if
422
423                         // Get previous group id
424                         $prevGroupId = $this->getPreviousGroupId();
425
426                         // Switch the state
427                         $this->closePreviousGroupByContent($content);
428
429                         // All call it again if the group name is not empty
430                         if ((!empty($groupId)) && ($groupId != $prevGroupId)) {
431                                 //* DEBUG: */ echo $groupId."/".$prevGroupId."<br />\n";
432                                 $this->addFormGroup($groupId, $groupText);
433                         } // END - if
434                 }
435         }
436
437         /**
438          * Add a form sub group or close an already opened and open a new one or
439          * throws an exception if no group has been opened before or if the sub
440          * group name is empty.
441          *
442          * @param       $subGroupId             Name of the group or last opened if empty
443          * @param       $subGroupText   Text including HTML to show above this group
444          * @return      void
445          * @throws      FormFormClosedException         If no group has been opened before
446          * @throws      EmptyVariableException          If $subGroupId is not set
447          */
448         public function addFormSubGroup ($subGroupId = "", $subGroupText = "") {
449                 // Is a group opened?
450                 if (!$this->ifGroupOpenedPreviously()) {
451                         // Throw exception here
452                         throw new FormFormClosedException(array($this, $subGroupId), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
453                 } // END - if
454
455                 // At least the sub group name should be set
456                 if ((empty($subGroupId)) && (!$this->ifSubGroupOpenedPreviously())) {
457                         // Throw exception here
458                         throw new EmptyVariableException(array($this, 'subGroupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
459                 } elseif (empty($subGroupId)) {
460                         // Close the last opened
461                         $subGroupId = $this->getPreviousSubGroupId();
462                 }
463
464                 // Same sub group to open?
465                 if ((!$this->ifSubGroupOpenedPreviously()) && ($subGroupId == $this->getPreviousSubGroupId())) {
466                         // Abort here silently
467                         return false;
468                 } // END - if
469
470                 // Initialize content with closing div by default
471                 $content = "    </div>\n</div><!-- Sub group- CLOSE //-->";
472
473                 // Is this group opened?
474                 if (!$this->ifSubGroupOpenedPreviously()) {
475                         // Begin the span block
476                         $content = sprintf("<!-- Sub group %s - OPEN //-->
477 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
478         <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
479                 %s
480         </span>
481         <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
482                                 $subGroupId,
483                                 $subGroupId,
484                                 $subGroupId,
485                                 $subGroupText,
486                                 $subGroupId
487                         );
488
489                         // Switch the state and remeber the name
490                         $this->openSubGroupByIdContent($subGroupId, $content);
491                 } else {
492                         // Get previous sub group id
493                         $prevSubGroupId = $this->getPreviousSubGroupId();
494
495                         // Switch the state
496                         $this->closePreviousSubGroupByContent($content);
497
498                         // All call it again if sub group name is not empty
499                         if ((!empty($subGroupId)) && ($subGroupId != $prevSubGroupId)) {
500                                 $this->addFormSubGroup($subGroupId, $subGroupText);
501                         } // END - if
502                 }
503         }
504
505         /**
506          * Add text surrounded by a span block when there is a group opened before
507          * or else by a div block.
508          *
509          * @param       $fieldName                      Field name
510          * @param       $fieldText                      Text for the field
511          * @return      void
512          * @throws      FormClosedException             If the form is not yet opened
513          */
514         public function addFieldText ($fieldName, $fieldText) {
515                 // Is the form opened?
516                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
517                         // Throw an exception
518                         throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
519                 } // END - if
520
521                 // Set the block type
522                 $block = "div";
523                 if ($this->ifGroupOpenedPreviously()) $block = "span";
524
525                 // Generate the content
526                 $inputContent = sprintf("       <%s id=\"%s_text\">
527                 %s
528         </%s>",
529                         $block,
530                         $fieldName,
531                         $fieldText,
532                         $block
533                 );
534
535                 // And add it
536                 $this->addContentToPreviousGroup($inputContent);
537         }
538
539         /**
540          * Add text (notes) surrounded by a div block.┬áStill opened groups or sub
541          * groups will be automatically closed.
542          *
543          * @param       $noteId         Id for this note
544          * @param       $formNotes      The form notes we shell addd
545          * @return      void
546          * @throws      FormClosedException             If the form is not yet opened
547          */
548         public function addFormNote ($noteId, $formNotes) {
549                 // Is the form opened?
550                 if (($this->formOpened === false) && ($this->formEnabled === true)) {
551                         // Throw an exception
552                         throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
553                 } // END - if
554
555                 // Is a group open?
556                 if ($this->ifGroupOpenedPreviously()) {
557                         // Then automatically close it here
558                         $this->addFormGroup();
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()) && ($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);
609                 } elseif ($this->getPreviousSubGroupId() != $selectId) {
610                         // Something went wrong!
611                         $this->debugInstance();
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()) {
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=\"%s\" class=\"suboption suboption_%s\" disabled=\"disabled\">%s</option>\n",
638                         $subName,
639                         $subName,
640                         $subValue
641                 );
642
643                 // Add the content to the previously opened sub group
644                 $this->addContentToPreviousGroup($content);
645         }
646
647         /**
648          * Adds a selectable option to a previously added selection box. This method
649          * does *not* validate if there is already a sub option added with the same
650          * name. We need to finish this here!
651          *
652          * @param       $optionName     Name of the sub action
653          * @param       $optionValue    Value of the sub action
654          * @return      void
655          * @throws      HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found
656          * @todo        Add checking if sub option is already added
657          */
658         public function addSelectOption ($optionName, $optionValue) {
659                 // Is there a sub group (shall be a selection box!)
660                 if (!$this->ifSubGroupOpenedPreviously()) {
661                         // Then throw an exception here
662                         throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
663                 } // END - if
664
665                 // Render the content
666                 $content = sprintf("<option value=\"%s\" class=\"option option_%s\">%s</option>\n",
667                         $optionName,
668                         $optionName,
669                         $optionValue
670                 );
671
672                 // Add the content to the previously opened sub group
673                 $this->addContentToPreviousGroup($content);
674         }
675
676         /**
677          * Adds a pre-configured CAPTCHA
678          *
679          * @return      void
680          */
681         public function addCaptcha () {
682                 // Get last executed pre filter
683                 $extraInstance = Registry::getRegistry()->getInstance('extra');
684
685                 // Get a configured instance
686                 $captchaInstance = ObjectFactory::createObjectByConfiguredName($this->getFormName().'_captcha', array($this, $extraInstance));
687
688                 // Initiate the CAPTCHA
689                 $captchaInstance->initiateCaptcha();
690
691                 // Render the CAPTCHA code
692                 $captchaInstance->renderCode();
693
694                 // Get the content and add it to the helper
695                 $this->addContentToPreviousGroup($captchaInstance->renderContent());
696         }
697
698         /**
699          * Enables/disables the form tag usage
700          *
701          * @param       $formEnabled    Wether form is enabled or disabled
702          * @return      void
703          */
704         public final function enableForm ($formEnabled = true) {
705                 $this->formEnabled = (bool) $formEnabled;
706         }
707
708         /**
709          * Setter for form name
710          *
711          * @param       $formName       Name of this form
712          * @return      void
713          */
714         public final function setFormName ($formName) {
715                 $this->formName = (string) $formName;
716         }
717
718         /**
719          * Getter for form name
720          *
721          * @return      $formName       Name of this form
722          */
723         public final function getFormName () {
724                 return $this->formName;
725         }
726
727         /**
728          * Checks wether the registration requires a valid email address
729          *
730          * @return      $required       Wether the email address is required
731          */
732         public function ifRegisterRequiresEmailVerification () {
733                 $required = ($this->getConfigInstance()->readConfig('register_requires_email') === "Y");
734                 return $required;
735         }
736
737         /**
738          * Checks wether profile data shall be asked
739          *
740          * @return      $required       Wether profile data shall be asked
741          */
742         public function ifRegisterIncludesProfile () {
743                 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') === "Y");
744                 return $required;
745         }
746
747         /**
748          * Checks wether this form is secured by a CAPTCHA
749          *
750          * @return      $isSecured      Wether this form is secured by a CAPTCHA
751          */
752         public function ifFormSecuredWithCaptcha () {
753                 $isSecured = ($this->getConfigInstance()->readConfig($this->getFormName().'_captcha_secured') === "Y");
754                 return $isSecured;
755         }
756
757         /**
758          * Flushs the content out (not yet secured against open forms, etc.!) or
759          * close the form automatically
760          *
761          * @return      void
762          * @throws      FormOpenedException             If the form is still open
763          */
764         public function flushContent () {
765                 // Is the form still open?
766                 if (($this->formOpened === true) && ($this->formEnabled === true)) {
767                         // Close the form automatically
768                         $this->addFormTag();
769                 } elseif ($this->formEnabled === false) {
770                         if ($this->ifSubGroupOpenedPreviously()) {
771                                 // Close sub group
772                                 $this->addFormSubGroup();
773                         } elseif ($this->ifGroupOpenedPreviously()) {
774                                 // Close group
775                                 $this->addFormGroup();
776                         }
777                 }
778
779                 // Send content to template engine
780                 //* DEBUG: */ echo __METHOD__.": form=".$this->getFormName().", size=".strlen($this->renderContent())."<br />\n";
781                 $this->getTemplateInstance()->assignVariable($this->getFormName(), $this->renderContent());
782         }
783 }
784
785 // [EOF]
786 ?>