3 * A helper for constructing web forms
5 * @author Roland Haeder <webmaster@ship-simu.org>
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
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.
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.
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/>.
24 class WebFormHelper extends BaseWebHelper implements HelpableTemplate {
26 * Wether the form tag is opened (keep at false or else your forms will
29 private $formOpened = false;
34 private $formName = "";
37 * Wether the group is opened or not
39 private $groupOpened = false;
42 * Wether the sub group is opened or not
44 private $subGroupOpened = false;
49 private $groupName = "";
52 * Name of the sub group
54 private $subGroupName = "";
57 * Wether form tag is enabled (default: true)
59 private $formEnabled = true;
62 const EXCEPTION_FORM_NAME_INVALID = 0x120;
63 const EXCEPTION_CLOSED_FORM = 0x121;
64 const EXCEPTION_OPENED_FORM = 0x122;
65 const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x123;
68 * Protected constructor
72 protected function __construct () {
73 // Call parent constructor
74 parent::__construct(__CLASS__);
76 // Set part description
77 $this->setObjectDescription("Helper class for HTML forms");
79 // Create unique ID number
80 $this->generateUniqueId();
84 * Creates the helper class with the given template engine instance and form name
86 * @param $templateInstance An instance of a valid template engine
87 * @param $formName Name of the form
88 * @param $formId Value for "id" attribute (default: $formName)
89 * @param $withForm Wether include the form tag
90 * @return $helperInstance A preparedf instance of this class
92 public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false, $withForm = true) {
94 $helperInstance = new WebFormHelper();
96 // Set template instance
97 $helperInstance->setTemplateInstance($templateInstance);
99 // Is the form id not set?
100 if ($formId === false) {
101 // Use form id from form name
106 $helperInstance->setFormName($formName);
107 // A form-less field may say "false" here...
108 if ($withForm === true) {
110 $helperInstance->addFormTag($formName, $formId);
113 $helperInstance->enableForm(false);
116 // Return the prepared instance
117 return $helperInstance;
121 * Add the form tag or close it an already opened form tag
123 * @param $formName Name of the form (default: false)
124 * @param $formId Id of the form (attribute "id"; default: false)
126 * @throws InvalidFormNameException If the form name is invalid (=false)
127 * @todo Add some unique PIN here to bypass problems with some browser and/or extensions
129 public function addFormTag ($formName = false, $formId = false) {
130 // When the form is not yet opened at least form name must be valid
131 if (($this->formOpened === false) && ($formName === false)) {
132 // Thrown an exception
133 throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
136 // Close the form is default
137 $formContent = "</form>";
139 // Check wether we shall open or close the form
140 if (($this->formOpened === false) && ($this->formEnabled === true)) {
142 $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
144 $this->getConfigInstance()->readConfig('base_url'),
145 $this->getConfigInstance()->readConfig('form_action'),
146 $this->getConfigInstance()->readConfig('form_method'),
147 $this->getConfigInstance()->readConfig('form_target')
150 // Add form id as well
151 $formContent .= sprintf(" id=\"%s_form\"",
158 // Open the form and remeber the form name
159 $this->formOpened = true;
161 // Add the hidden field required to identify safely this form
162 $this->addInputHiddenField('form', $this->getFormName());
165 if ($this->groupOpened === true) {
166 // Then automatically close it here
167 $this->addFormGroup();
171 $this->formOpened = false;
174 // Add it to the content
175 $this->addContent($formContent);
179 * Add a text input tag to the form or throw an exception if it is not yet
180 * opened. The field's name will be set as id.
182 * @param $fieldName Input field name
183 * @param $fieldValue Input default value (default: empty)
185 * @throws FormClosedException If the form is not yet opened
187 public function addInputTextField ($fieldName, $fieldValue = "") {
188 // Is the form opened?
189 if (($this->formOpened === false) && ($this->formEnabled === true)) {
190 // Throw an exception
191 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
194 // Generate the content
195 $inputContent = sprintf("<input type=\"text\" class=\"textfield %s_field\" name=\"%s\" value=\"%s\" />",
201 // And add it maybe with a "li" tag
202 $this->addContent($inputContent);
206 * Add a text input tag to the form with pre-loaded default value
208 * @param $fieldName Input field name
211 public function addInputTextFieldWithDefault ($fieldName) {
212 // Get the value from instance
213 $fieldValue = $this->getField($fieldName);
214 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
216 // Add the text field
217 $this->addInputTextField($fieldName, $fieldValue);
221 * Add a password input tag to the form or throw an exception if it is not
222 * yet opened. The field's name will be set as id.
224 * @param $fieldName Input field name
225 * @param $fieldValue Input default value (default: empty)
227 * @throws FormClosedException If the form is not yet opened
229 public function addInputPasswordField ($fieldName, $fieldValue = "") {
230 // Is the form opened?
231 if (($this->formOpened === false) && ($this->formEnabled === true)) {
232 // Throw an exception
233 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
236 // Generate the content
237 $inputContent = sprintf("<input type=\"password\" class=\"password %s_field\" name=\"%s\" value=\"%s\" />",
244 $this->addContent($inputContent);
248 * Add a hidden input tag to the form or throw an exception if it is not
249 * yet opened. The field's name will be set as id.
251 * @param $fieldName Input field name
252 * @param $fieldValue Input default value (default: empty)
254 * @throws FormClosedException If the form is not yet opened
256 public function addInputHiddenField ($fieldName, $fieldValue = "") {
257 // Is the form opened?
258 if (($this->formOpened === false) && ($this->formEnabled === true)) {
259 // Throw an exception
260 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
263 // Generate the content
264 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
270 $this->addContent($inputContent);
274 * Add a hidden input tag to the form with pre-loaded default value
276 * @param $fieldName Input field name
279 public function addInputHiddenFieldWithDefault ($fieldName) {
280 // Get the value from instance
281 $fieldValue = $this->getField($fieldName);
282 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
284 // Add the text field
285 $this->addInputHiddenField($fieldName, $fieldValue);
289 * Add a hidden input tag to the form with configuration value
291 * @param $fieldName Input field name
292 * @param $prefix Prefix for configuration without trailing _
295 public function addInputHiddenConfiguredField ($fieldName, $prefix) {
296 // Get the value from instance
297 $fieldValue = $this->getConfigInstance()->readConfig("{$prefix}_{$fieldName}");
298 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
300 // Add the text field
301 $this->addInputHiddenField($fieldName, $fieldValue);
305 * Add a checkbox input tag to the form or throw an exception if it is not
306 * yet opened. The field's name will be set as id.
308 * @param $fieldName Input field name
309 * @param $fieldChecked Wether the field is checked (defaut: checked)
311 * @throws FormClosedException If the form is not yet opened
313 public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
314 // Is the form opened?
315 if (($this->formOpened === false) && ($this->formEnabled === true)) {
316 // Throw an exception
317 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
320 // Set wether the check box is checked...
321 $checked = " checked=\"checked\"";
322 if ($fieldChecked === false) $checked = " ";
324 // Generate the content
325 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox %s_field\" value=\"1\"%s/>",
332 $this->addContent($inputContent);
336 * Add a reset input tag to the form or throw an exception if it is not
337 * yet opened. The field's name will be set as id.
339 * @param $buttonText Text displayed on the button
341 * @throws FormClosedException If the form is not yet opened
343 public function addInputResetButton ($buttonText) {
344 // Is the form opened?
345 if (($this->formOpened === false) && ($this->formEnabled === true)) {
346 // Throw an exception
347 throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
350 // Generate the content
351 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
352 $this->getFormName(),
357 $this->addContent($inputContent);
361 * Add a reset input tag to the form or throw an exception if it is not
362 * yet opened. The field's name will be set as id.
364 * @param $buttonText Text displayed on the button
366 * @throws FormClosedException If the form is not yet opened
368 public function addInputSubmitButton ($buttonText) {
369 // Is the form opened?
370 if (($this->formOpened === false) && ($this->formEnabled === true)) {
371 // Throw an exception
372 throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
375 // Generate the content
376 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
377 $this->getFormName(),
378 $this->getFormName(),
383 $this->addContent($inputContent);
387 * Add a form group or close an already opened and open a new one
389 * @param $groupName Name of the group or last opened if empty
390 * @param $groupText Text including HTML to show above this group
392 * @throws FormClosedException If no form has been opened before
393 * @throws EmptyVariableException If $groupName is not set
395 public function addFormGroup ($groupName = "", $groupText = "") {
397 if (($this->formOpened === false) && ($this->formEnabled === true)) {
398 // Throw exception here
399 throw new FormClosedException(array($this, $groupName), self::EXCEPTION_CLOSED_FORM);
402 // At least the group name should be set
403 if ((empty($groupName)) && ($this->groupOpened === false)) {
404 // Throw exception here
405 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
406 } elseif (empty($groupName)) {
407 // Close the last opened
408 $groupName = $this->groupName;
411 // Same group to open?
412 if (($this->groupOpened === false) && ($groupName == $this->groupName)) {
413 // Abort here silently
417 // Initialize content with closing div by default
418 $content = " </div>\n</div><!-- Group - CLOSE //-->";
420 // Is this group opened?
421 if ($this->groupOpened === false) {
422 // Begin the div/span blocks
423 $content = sprintf("<!-- Group %s - OPEN //-->
424 <div class=\"group_box\" id=\"%s_group_box\">
425 <span class=\"group_text\" id=\"%s_group_text\">
428 <div class=\"group_field\" id=\"%s_group_field\">",
437 $this->addContent($content);
440 $this->groupName = $groupName;
441 $this->groupOpened = true;
443 // Is a sub group opened?
444 if ($this->subGroupOpened === true) {
446 $this->addFormSubGroup();
450 $this->addContent($content);
453 $this->groupOpened = false;
455 // All call it again if the group name is not empty
456 if (!empty($groupName)) {
457 $this->addFormGroup($groupName, $groupText);
463 * Add a form sub group or close an already opened and open a new one or
464 * throws an exception if no group has been opened before or if the sub
465 * group name is empty.
467 * @param $subGroupName Name of the group or last opened if empty
468 * @param $subGroupText Text including HTML to show above this group
470 * @throws FormGroupClosedException If no group has been opened before
471 * @throws EmptyVariableException If $subGroupName is not set
473 public function addFormSubGroup ($subGroupName = "", $subGroupText = "") {
474 // Is a group opened?
475 if ($this->groupOpened === false) {
476 // Throw exception here
477 throw new FormGroupClosedException(array($this, $subGroupName), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
480 // At least the sub group name should be set
481 if ((empty($subGroupName)) && ($this->subGroupOpened === false)) {
482 // Throw exception here
483 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
484 } elseif (empty($subGroupName)) {
485 // Close the last opened
486 $subGroupName = $this->subGroupName;
489 // Same sub group to open?
490 if (($this->subGroupOpened === false) && ($subGroupName == $this->subGroupName)) {
491 // Abort here silently
495 // Initialize content with closing div by default
496 $content = " </div>\n</div><!-- Sub group- CLOSE //-->";
498 // Is this group opened?
499 if ($this->subGroupOpened === false) {
500 // Begin the span block
501 $content = sprintf("<!-- Sub group %s - OPEN //-->
502 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
503 <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
506 <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
515 $this->addContent($content);
517 // Switch the state and remeber the name
518 $this->subGroupOpened = true;
519 $this->subGroupName = $subGroupName;
522 $this->addContent($content);
525 $this->subGroupOpened = false;
527 // All call it again if sub group name is not empty
528 if (!empty($subGroupName)) {
529 $this->addFormSubGroup($subGroupName, $subGroupText);
535 * Add text surrounded by a span block when there is a group opened before
536 * or else by a div block.
538 * @param $fieldName Field name
539 * @param $fieldText Text for the field
541 * @throws FormClosedException If the form is not yet opened
543 public function addFieldText ($fieldName, $fieldText) {
544 // Is the form opened?
545 if (($this->formOpened === false) && ($this->formEnabled === true)) {
546 // Throw an exception
547 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
550 // Set the block type
552 if ($this->groupOpened === true) $block = "span";
554 // Generate the content
555 $inputContent = sprintf(" <%s id=\"%s_text\">
565 $this->addContent($inputContent);
569 * Add text (notes) surrounded by a div block. Still opened groups or sub
570 * groups will be automatically closed.
572 * @param $noteId Id for this note
573 * @param $formNotes The form notes we shell addd
575 * @throws FormClosedException If the form is not yet opened
577 public function addFormNote ($noteId, $formNotes) {
578 // Is the form opened?
579 if (($this->formOpened === false) && ($this->formEnabled === true)) {
580 // Throw an exception
581 throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
585 if ($this->groupOpened === true) {
586 // Then automatically close it here
587 $this->addFormGroup();
590 // Generate the content
591 $inputContent = sprintf(" <div id=\"form_note_%s\">
599 $this->addContent($inputContent);
603 * Checks wether the registration requires a valid email address
605 * @return $required Wether the email address is required
607 public function ifRegisterRequiresEmailVerification () {
608 $required = ($this->getConfigInstance()->readConfig('register_requires_email') === "Y");
613 * Checks wether profile data shall be asked
615 * @return $required Wether profile shall be asked
617 public function ifRegisterIncludesProfile () {
618 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') === "Y");
623 * Adds a pre-configured CAPTCHA
627 public function addCaptcha () {
628 // Get last executed pre filter
629 $extraInstance = Registry::getRegistry()->getInstance('extra');
631 // Get a configured instance
632 $captchaInstance = ObjectFactory::createObjectByConfiguredName($this->getFormName()."_captcha", array($this, $extraInstance));
634 // Initiate the CAPTCHA
635 $captchaInstance->initiateCaptcha();
637 // Render the CAPTCHA code
638 $captchaInstance->renderCode();
640 // Get the content and add it to the helper
641 $this->addContent($captchaInstance->getContent());
645 * Enables/disables the form tag usage
647 * @param $formEnabled Wether form is enabled or disabled
650 public final function enableForm ($formEnabled = true) {
651 $this->formEnabled = (bool) $formEnabled;
655 * Setter for form name
657 * @param $formName Name of this form
660 public final function setFormName ($formName) {
661 $this->formName = (string) $formName;
665 * Getter for form name
667 * @return $formName Name of this form
669 public final function getFormName () {
670 return $this->formName;
674 * Checks wether this form is secured by a CAPTCHA
676 * @return $isSecured Wether this form is secured by a CAPTCHA
678 public function ifFormSecuredWithCaptcha () {
679 $isSecured = ($this->getConfigInstance()->readConfig($this->getFormName().'_captcha_secured') === "Y");
684 * Flushs the content out (not yet secured against open forms, etc.!) or
685 * close the form automatically
688 * @throws FormOpenedException If the form is still open
690 public function flushContent () {
691 // Is the form still open?
692 if (($this->formOpened === true) && ($this->formEnabled === true)) {
693 // Close the form automatically
695 } elseif ($this->formEnabled === false) {
696 if ($this->subGroupOpened === true) {
698 $this->addFormSubGroup();
699 } elseif ($this->groupOpened === true) {
701 $this->addFormGroup();
705 // Send content to template engine
706 //* DEBUG: */ echo __METHOD__.": form=".$this->getFormName().", size=".strlen($this->getContent())."<br />\n";
707 $this->getTemplateInstance()->assignVariable($this->getFormName(), $this->getContent());