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 BaseHelper {
26 * Instance to the class which provides field values
28 private $valueInstance = null;
31 * Wether the form tag is opened (keep at false or else your forms will
34 private $formOpened = false;
39 private $formName = "";
42 * Wether the group is opened or not
44 private $groupOpened = false;
47 * Wether the sub group is opened or not
49 private $subGroupOpened = false;
52 * Name of the sub group
54 private $subGroupName = "";
57 const EXCEPTION_FORM_NAME_INVALID = 0x030;
58 const EXCEPTION_CLOSED_FORM = 0x031;
59 const EXCEPTION_OPENED_FORM = 0x032;
60 const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x033;
63 * Protected constructor
67 protected function __construct () {
68 // Call parent constructor
69 parent::__construct(__CLASS__);
71 // Set part description
72 $this->setObjectDescription("Helper class for HTML forms");
74 // Create unique ID number
75 $this->generateUniqueId();
79 * Creates the helper class with the given template engine instance and form name
81 * @param $templateInstance An instance of a valid template engine
82 * @param $formName Name of the form
83 * @param $formId Value for "id" attribute (default: $formName)
84 * @return $helperInstance A preparedf instance of this class
86 public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) {
88 $helperInstance = new WebFormHelper();
90 // Set template instance
91 $helperInstance->setTemplateInstance($templateInstance);
93 // Is the form id not set?
94 if ($formId === false) {
95 // Use form id from form name
100 $helperInstance->addFormTag($formName, $formId);
102 // Return the prepared instance
103 return $helperInstance;
107 * Pre-fetches field default values from the given registry key instance into this class
109 * @param $registryKey
111 * @throws NullPointerException If an instance from registry is null
113 public function prefetchFieldValues ($registryKey) {
114 // Get the required instance
115 $this->valueInstance = Registry::getRegistry()->getInstance($registryKey);
117 // Is the instance valid?
118 if (is_null($this->valueInstance)) {
119 // Throw an exception
120 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
125 * Add the form tag or close it an already opened form tag
127 * @param $formName Name of the form (default: false)
128 * @param $formId Id of the form (attribute "id"; default: false)
130 * @throws InvalidFormNameException If the form name is invalid (=false)
131 * @todo Add some unique PIN here to bypass problems with some browser and/or extensions
133 public function addFormTag ($formName = false, $formId = false) {
134 // When the form is not yet opened at least form name must be valid
135 if (($this->formOpened === false) && ($formName === false)) {
136 // Thrown an exception
137 throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
140 // Close the form is default
141 $formContent = "</form>";
143 // Check wether we shall open or close the form
144 if ($this->formOpened === false) {
146 $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
148 $this->getConfigInstance()->readConfig('base_url'),
149 $this->getConfigInstance()->readConfig('form_action'),
150 $this->getConfigInstance()->readConfig('form_method'),
151 $this->getConfigInstance()->readConfig('form_target')
154 // Is the form id set?
155 if ($formId !== false) {
156 // Then add it as well
157 $formContent .= sprintf(" id=\"%s_form\"",
165 // Open the form and remeber the form name
166 $this->formOpened = true;
167 $this->formName = $formName;
169 // Add the hidden field required to identify safely this form
170 $this->addInputHiddenField('form', $this->formName);
173 if ($this->groupOpened === true) {
174 // Then automatically close it here
175 $this->addFormGroup("", "");
179 $this->formOpened = false;
182 // Add it to the content
183 $this->addContent($formContent);
187 * Add a text input tag to the form or throw an exception if it is not yet
188 * opened. The field's name will be set as id.
190 * @param $fieldName Input field name
191 * @param $fieldValue Input default value (default: empty)
193 * @throws FormClosedException If the form is not yet opened
195 public function addInputTextField ($fieldName, $fieldValue = "") {
196 // Is the form opened?
197 if ($this->formOpened === false) {
198 // Throw an exception
199 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
202 // Generate the content
203 $inputContent = sprintf("<input type=\"text\" class=\"textfield\" id=\"%s_field\" name=\"%s\" value=\"%s\" />",
209 // And add it maybe with a "li" tag
210 $this->addContent($inputContent);
214 * Add a text input tag to the form with pre-loaded default value
216 * @param $fieldName Input field name
219 public function addInputTextFieldWithDefault ($fieldName) {
220 // Get the value from instance
221 $fieldValue = $this->getField($fieldName);
222 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
224 // Add the text field
225 $this->addInputTextField($fieldName, $fieldValue);
229 * Add a password input tag to the form or throw an exception if it is not
230 * yet opened. The field's name will be set as id.
232 * @param $fieldName Input field name
233 * @param $fieldValue Input default value (default: empty)
235 * @throws FormClosedException If the form is not yet opened
237 public function addInputPasswordField ($fieldName, $fieldValue = "") {
238 // Is the form opened?
239 if ($this->formOpened === false) {
240 // Throw an exception
241 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
244 // Generate the content
245 $inputContent = sprintf("<input type=\"password\" class=\"password\" id=\"%s_field\" name=\"%s\" value=\"%s\" />",
252 $this->addContent($inputContent);
256 * Add a hidden input tag to the form or throw an exception if it is not
257 * yet opened. The field's name will be set as id.
259 * @param $fieldName Input field name
260 * @param $fieldValue Input default value (default: empty)
262 * @throws FormClosedException If the form is not yet opened
264 public function addInputHiddenField ($fieldName, $fieldValue = "") {
265 // Is the form opened?
266 if ($this->formOpened === false) {
267 // Throw an exception
268 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
271 // Generate the content
272 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
278 $this->addContent($inputContent);
282 * Add a hidden input tag to the form with pre-loaded default value
284 * @param $fieldName Input field name
287 public function addInputHiddenFieldWithDefault ($fieldName) {
288 // Get the value from instance
289 $fieldValue = $this->getField($fieldName);
290 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
292 // Add the text field
293 $this->addInputHiddenField($fieldName, $fieldValue);
297 * Add a hidden input tag to the form with configuration value
299 * @param $fieldName Input field name
300 * @param $prefix Prefix for configuration without trailing _
303 public function addInputHiddenConfiguredField ($fieldName, $prefix) {
304 // Get the value from instance
305 $fieldValue = $this->getConfigInstance()->readConfig("{$prefix}_{$fieldName}");
306 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
308 // Add the text field
309 $this->addInputHiddenField($fieldName, $fieldValue);
313 * Add a checkbox input tag to the form or throw an exception if it is not
314 * yet opened. The field's name will be set as id.
316 * @param $fieldName Input field name
317 * @param $fieldChecked Wether the field is checked (defaut: checked)
319 * @throws FormClosedException If the form is not yet opened
321 public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
322 // Is the form opened?
323 if ($this->formOpened === false) {
324 // Throw an exception
325 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
328 // Set wether the check box is checked...
329 $checked = " checked=\"checked\"";
330 if ($fieldChecked === false) $checked = " ";
332 // Generate the content
333 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox\" id=\"%s_field\" value=\"1\"%s/>",
340 $this->addContent($inputContent);
344 * Add a reset input tag to the form or throw an exception if it is not
345 * yet opened. The field's name will be set as id.
347 * @param $buttonText Text displayed on the button
349 * @throws FormClosedException If the form is not yet opened
351 public function addInputResetButton ($buttonText) {
352 // Is the form opened?
353 if ($this->formOpened === false) {
354 // Throw an exception
355 throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
358 // Generate the content
359 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
365 $this->addContent($inputContent);
369 * Add a reset input tag to the form or throw an exception if it is not
370 * yet opened. The field's name will be set as id.
372 * @param $buttonText Text displayed on the button
374 * @throws FormClosedException If the form is not yet opened
376 public function addInputSubmitButton ($buttonText) {
377 // Is the form opened?
378 if ($this->formOpened === false) {
379 // Throw an exception
380 throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
383 // Generate the content
384 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
391 $this->addContent($inputContent);
395 * Add a form group or close an already opened and open a new one
397 * @param $groupName Name of the group
398 * @param $groupText Text including HTML to show above this group
400 * @throws FormClosedException If no form has been opened before
401 * @throws EmptyVariableException If $groupName is not set
403 public function addFormGroup ($groupName, $groupText) {
405 if ($this->formOpened === false) {
406 // Throw exception here
407 throw new FormClosedException(array($this, $groupName), self::EXCEPTION_CLOSED_FORM);
410 // At least the group name should be set
411 if ((empty($groupName)) && ($this->groupOpened === false)) {
412 // Throw exception here
413 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
416 // Initialize content with closing div by default
417 $content = " </div>\n</div><!-- Group - CLOSE //-->";
419 // Is this group opened?
420 if ($this->groupOpened === false) {
421 // Begin the div/span blocks
422 $content = sprintf("<!-- Group %s - OPEN //-->
423 <div class=\"group_box\" id=\"%s_group_box\">
424 <span class=\"group_text\" id=\"%s_group_text\">
427 <div class=\"group_field\" id=\"%s_group_field\">",
436 $this->addContent($content);
439 $this->groupOpened = true;
441 // Is a sub group opened?
442 if ($this->subGroupOpened === true) {
444 $this->addFormSubGroup("", "");
448 $this->addContent($content);
451 $this->groupOpened = false;
453 // All call it again if the group name is not empty
454 if (!empty($groupName)) {
455 $this->addFormGroup($groupName, $groupText);
461 * Add a form sub group or close an already opened and open a new one or
462 * throws an exception if no group has been opened before or if the sub
463 * group name is empty.
465 * @param $subGroupName Name of the group
466 * @param $subGroupText Text including HTML to show above this group
468 * @throws FormGroupClosedException If no group has been opened before
469 * @throws EmptyVariableException If $subGroupName is not set
471 public function addFormSubGroup ($subGroupName, $subGroupText) {
472 // Is a group opened?
473 if ($this->groupOpened === false) {
474 // Throw exception here
475 throw new FormGroupClosedException(array($this, $subGroupName), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
478 // At least the sub group name should be set
479 if ((empty($subGroupName)) && ($this->subGroupOpened === false)) {
480 // Throw exception here
481 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
484 // Initialize content with closing div by default
485 $content = " </div>\n</div><!-- Sub group- CLOSE //-->";
487 // Is this group opened?
488 if ($this->subGroupOpened === false) {
489 // Begin the span block
490 $content = sprintf("<!-- Sub group %s - OPEN //-->
491 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
492 <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
495 <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
504 $this->addContent($content);
506 // Switch the state and remeber the name
507 $this->subGroupOpened = true;
508 $this->subGroupName = $subGroupName;
511 $this->addContent($content);
514 $this->subGroupOpened = false;
516 // All call it again if sub group name is not empty
517 if (!empty($subGroupName)) {
518 $this->addFormSubGroup($subGroupName, $subGroupText);
524 * Add text surrounded by a span block when there is a group opened before
525 * or else by a div block.
527 * @param $fieldName Field name
528 * @param $fieldText Text for the field
530 * @throws FormClosedException If the form is not yet opened
532 public function addFieldText ($fieldName, $fieldText) {
533 // Is the form opened?
534 if ($this->formOpened === false) {
535 // Throw an exception
536 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
539 // Set the block type
541 if ($this->groupOpened === true) $block = "span";
543 // Generate the content
544 $inputContent = sprintf(" <%s id=\"%s_text\">
554 $this->addContent($inputContent);
558 * Add text (notes) surrounded by a div block. Still opened groups or sub
559 * groups will be automatically closed.
561 * @param $formNotes The form notes we shell addd
563 * @throws FormClosedException If the form is not yet opened
565 public function addFormNote ($formNotes) {
566 // Is the form opened?
567 if ($this->formOpened === false) {
568 // Throw an exception
569 throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
573 if ($this->groupOpened === true) {
574 // Then automatically close it here
575 $this->addFormGroup("", "");
578 // Generate the content
579 $inputContent = sprintf(" <div id=\"form_note\">
586 $this->addContent($inputContent);
590 * Checks wether the registration requires a valid email address
592 * @return $required Wether the email address is required
594 public function ifRegisterRequiresEmailVerification () {
595 $required = ($this->getConfigInstance()->readConfig('register_requires_email') == "Y");
600 * Checks wether profile data shall be asked
602 * @return $required Wether profile shall be asked
604 public function ifRegisterIncludesProfile () {
605 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') == "Y");
610 * Checks wether personal data shall be asked
612 * @return $required Wether personal data shall be asked
614 public function ifRegisterIncludesPersonaData () {
615 $required = ($this->getConfigInstance()->readConfig('register_personal_data') == "Y");
620 * Checks wether email addresses can only be once used
624 public function ifEmailMustBeUnique () {
625 $isUnique = ($this->getConfigInstance()->readConfig('register_email_unique') == "Y");
630 * Checks wether the specified chat protocol is enabled in this form
632 * @return $required Wether the specified chat protocol is enabled
634 public function ifChatEnabled ($chatProtocol) {
635 $required = ($this->getConfigInstance()->readConfig(sprintf("chat_enabled_%s", $chatProtocol)) == "Y");
640 * Checks wether login is enabled or disabled
642 * @return $isEnabled Wether the login is enabled or disabled
644 public function ifLoginIsEnabled () {
645 $isEnabled = ($this->getConfigInstance()->readConfig('login_enabled') == "Y");
650 * Checks wether login shall be done by username
652 * @return $isEnabled Wether the login shall be done by username
654 public function ifLoginWithUsername () {
655 $isEnabled = ($this->getConfigInstance()->readConfig('login_type') == "username");
660 * Checks wether login shall be done by email
662 * @return $isEnabled Wether the login shall be done by email
664 public function ifLoginWithEmail () {
665 $isEnabled = ($this->getConfigInstance()->readConfig('login_type') == "email");
670 * Checks wether guest login is allowed
672 * @return $isAllowed Wether guest login is allowed
674 public function ifGuestLoginAllowed () {
675 $isAllowed = ($this->getConfigInstance()->readConfig('guest_login_allowed') == "Y");
680 * Checks wether the email address change must be confirmed
682 * @return $requireConfirm Wether email change must be confirmed
684 public function ifEmailChangeRequireConfirmation () {
685 $requireConfirm = ($this->getConfigInstance()->readConfig('email_change_confirmation') == "Y");
686 return $requireConfirm;
690 * Checks wether the rules has been updated
692 * @return $rulesUpdated Wether rules has been updated
693 * @todo Implement check if rules have been changed
695 public function ifRulesHaveChanged () {
700 * Checks wether email change is allowed
702 * @return $emailChange Wether changing email address is allowed
704 public function ifEmailChangeAllowed () {
705 $emailChange = ($this->getConfigInstance()->readConfig('email_change_allowed') == "Y");
710 * Checks wether the user account is unconfirmed
712 * @return $isUnconfirmed Wether the user account is unconfirmed
714 public function ifUserAccountUnconfirmed () {
715 $isUnconfirmed = ($this->getField('user_status') === $this->getConfigInstance()->readConfig('user_status_unconfirmed'));
716 return $isUnconfirmed;
720 * Checks wether the user account is locked
722 * @return $isUnconfirmed Wether the user account is locked
724 public function ifUserAccountLocked () {
725 $isUnconfirmed = ($this->getField('user_status') === $this->getConfigInstance()->readConfig('user_status_locked'));
726 return $isUnconfirmed;
730 * Checks wether the user account is a guest
732 * @return $isUnconfirmed Wether the user account is a guest
734 public function ifUserAccountGuest () {
735 $isUnconfirmed = ($this->getField('user_status') === $this->getConfigInstance()->readConfig('user_status_guest'));
736 return $isUnconfirmed;
740 * Checks wether this form is secured by a CAPTCHA
742 * @return $isSecured Wether this form is secured by a CAPTCHA
744 public function ifFormSecuredWithCaptcha () {
745 $isSecured = ($this->getConfigInstance()->readConfig($this->formName."_captcha_secured") == "Y");
750 * Flushs the content out (not yet secured against open forms, etc.!) or
751 * close the form automatically
754 * @throws FormOpenedException If the form is still open
756 public function flushContent () {
757 // Is the form still open?
758 if ($this->formOpened === true) {
759 // Close the form automatically
763 // Send content to template engine
764 $this->getTemplateInstance()->assignVariable($this->formName, $this->getContent());
768 * Getter for direct field values
770 * @param $fieldName Name of the field we shall fetch
771 * @return $fieldValue Value from field
773 public function getField ($fieldName) {
774 // Get the field value
775 $fieldValue = call_user_func_array(array($this->valueInstance, 'getField'), array($fieldName));
782 * Adds a pre-configured CAPTCHA
786 public function addCaptcha () {
787 // Get last executed pre filter
788 $extraInstance = Registry::getRegistry()->getInstance('extra');
790 // Get a configured instance
791 $captchaInstance = ObjectFactory::createObjectByConfiguredName("{$this->formName}_captcha", array($this->getTemplateInstance(), $extraInstance));
793 // Initiate the CAPTCHA
794 $captchaInstance->initiateCaptcha();
796 // Render the CAPTCHA code
797 $captchaInstance->renderCode();
799 // Get the content and add it to the helper
800 $this->addContent($captchaInstance->getContent());