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 form tag is enabled (default: true)
39 private $formEnabled = true;
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;
48 * Protected constructor
52 protected function __construct () {
53 // Call parent constructor
54 parent::__construct(__CLASS__);
58 * Creates the helper class with the given template engine instance and form name
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
66 public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false, $withForm = true) {
68 $helperInstance = new WebFormHelper();
70 // Set template instance
71 $helperInstance->setTemplateInstance($templateInstance);
73 // Is the form id not set?
74 if ($formId === false) {
75 // Use form id from form name
80 $helperInstance->setFormName($formName);
82 // A form-less field may say "false" here...
83 if ($withForm === true) {
85 $helperInstance->addFormTag($formName, $formId);
88 $helperInstance->enableForm(false);
91 // Return the prepared instance
92 return $helperInstance;
96 * Add the form tag or close it an already opened form tag
98 * @param $formName Name of the form (default: false)
99 * @param $formId Id of the form (attribute "id"; default: false)
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
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);
111 // Close the form is default
112 $formContent = "</form>";
114 // Check wether we shall open or close the form
115 if (($this->formOpened === false) && ($this->formEnabled === true)) {
117 $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
119 $this->getConfigInstance()->readConfig('base_url'),
120 $this->getConfigInstance()->readConfig('form_action'),
121 $this->getConfigInstance()->readConfig('form_method'),
122 $this->getConfigInstance()->readConfig('form_target')
125 // Add form id as well
126 $formContent .= sprintf(" id=\"%s_form\"",
133 // Open the form and remeber the form name
134 $this->formOpened = true;
136 // Add the hidden field required to identify safely this form
137 $this->addInputHiddenField('form', $this->getFormName());
140 if ($this->ifGroupOpenedPreviously()) {
141 // Then automatically close it here
142 $this->addFormGroup();
146 $this->formOpened = false;
149 // Add it to the content
150 $this->addContent($formContent);
154 * Add a text input tag to the form or throw an exception if it is not yet
155 * opened. The field's name will be set as id.
157 * @param $fieldName Input field name
158 * @param $fieldValue Input default value (default: empty)
160 * @throws FormClosedException If the form is not yet opened
162 public function addInputTextField ($fieldName, $fieldValue = "") {
163 // Is the form opened?
164 if (($this->formOpened === false) && ($this->formEnabled === true)) {
165 // Throw an exception
166 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
169 // Generate the content
170 $inputContent = sprintf("<input type=\"text\" class=\"textfield %s_field\" name=\"%s\" value=\"%s\" />",
176 // And add it maybe with a "li" tag
177 $this->addContent($inputContent);
181 * Add a text input tag to the form with pre-loaded default value
183 * @param $fieldName Input field name
186 public function addInputTextFieldWithDefault ($fieldName) {
187 // Get the value from instance
188 $fieldValue = $this->getValueField($fieldName);
189 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
191 // Add the text field
192 $this->addInputTextField($fieldName, $fieldValue);
196 * Add a password input tag to the form or throw an exception if it is not
197 * yet opened. The field's name will be set as id.
199 * @param $fieldName Input field name
200 * @param $fieldValue Input default value (default: empty)
202 * @throws FormClosedException If the form is not yet opened
204 public function addInputPasswordField ($fieldName, $fieldValue = "") {
205 // Is the form opened?
206 if (($this->formOpened === false) && ($this->formEnabled === true)) {
207 // Throw an exception
208 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
211 // Generate the content
212 $inputContent = sprintf("<input type=\"password\" class=\"password %s_field\" name=\"%s\" value=\"%s\" />",
219 $this->addContent($inputContent);
223 * Add a hidden input tag to the form or throw an exception if it is not
224 * yet opened. The field's name will be set as id.
226 * @param $fieldName Input field name
227 * @param $fieldValue Input default value (default: empty)
229 * @throws FormClosedException If the form is not yet opened
231 public function addInputHiddenField ($fieldName, $fieldValue = "") {
232 // Is the form opened?
233 if (($this->formOpened === false) && ($this->formEnabled === true)) {
234 // Throw an exception
235 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
238 // Generate the content
239 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
245 $this->addContent($inputContent);
249 * Add a hidden input tag to the form with pre-loaded default value
251 * @param $fieldName Input field name
254 public function addInputHiddenFieldWithDefault ($fieldName) {
255 // Get the value from instance
256 $fieldValue = $this->getValueField($fieldName);
257 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
259 // Add the text field
260 $this->addInputHiddenField($fieldName, $fieldValue);
264 * Add a hidden input tag to the form with configuration value
266 * @param $fieldName Input field name
267 * @param $prefix Prefix for configuration without trailing _
270 public function addInputHiddenConfiguredField ($fieldName, $prefix) {
271 // Get the value from instance
272 $fieldValue = $this->getConfigInstance()->readConfig("{$prefix}_{$fieldName}");
273 //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."<br />\n";
275 // Add the text field
276 $this->addInputHiddenField($fieldName, $fieldValue);
280 * Add a checkbox input tag to the form or throw an exception if it is not
281 * yet opened. The field's name will be set as id.
283 * @param $fieldName Input field name
284 * @param $fieldChecked Wether the field is checked (defaut: checked)
286 * @throws FormClosedException If the form is not yet opened
288 public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
289 // Is the form opened?
290 if (($this->formOpened === false) && ($this->formEnabled === true)) {
291 // Throw an exception
292 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
295 // Set wether the check box is checked...
296 $checked = " checked=\"checked\"";
297 if ($fieldChecked === false) $checked = " ";
299 // Generate the content
300 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox %s_field\" value=\"1\"%s/>",
307 $this->addContent($inputContent);
311 * Add a reset input tag to the form or throw an exception if it is not
312 * yet opened. The field's name will be set as id.
314 * @param $buttonText Text displayed on the button
316 * @throws FormClosedException If the form is not yet opened
318 public function addInputResetButton ($buttonText) {
319 // Is the form opened?
320 if (($this->formOpened === false) && ($this->formEnabled === true)) {
321 // Throw an exception
322 throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
325 // Generate the content
326 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
327 $this->getFormName(),
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 addInputSubmitButton ($buttonText) {
344 // Is the form opened?
345 if (($this->formOpened === false) && ($this->formEnabled === true)) {
346 // Throw an exception
347 throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
350 // Generate the content
351 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
352 $this->getFormName(),
353 $this->getFormName(),
358 $this->addContent($inputContent);
362 * Add a form group or close an already opened and open a new one
364 * @param $groupId Name of the group or last opened if empty
365 * @param $groupText Text including HTML to show above this group
367 * @throws FormClosedException If no form has been opened before
368 * @throws EmptyVariableException If $groupId is not set
370 public function addFormGroup ($groupId = "", $groupText = "") {
372 if (($this->formOpened === false) && ($this->formEnabled === true)) {
373 // Throw exception here
374 throw new FormClosedException(array($this, $groupId), self::EXCEPTION_CLOSED_FORM);
377 // At least the group name should be set
378 if ((empty($groupId)) && (!$this->ifGroupOpenedPreviously())) {
379 // Throw exception here
380 throw new EmptyVariableException(array($this, 'groupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
381 } elseif (empty($groupId)) {
382 // Close the last opened
383 $groupId = $this->getPreviousGroupId();
386 // Same group to open?
387 if ((!$this->ifGroupOpenedPreviously()) && ($groupId == $this->getPreviousGroupId())) {
388 // Abort here silently
392 // Initialize content with closing div by default
393 $content = " </div>\n</div><!-- Group - CLOSE //-->";
395 // Is this group opened?
396 if (!$this->ifGroupOpenedPreviously()) {
397 // Begin the div/span blocks
398 $content = sprintf("<!-- Group %s - OPEN //-->
399 <div class=\"group_box\" id=\"%s_group_box\">
400 <span class=\"group_text\" id=\"%s_group_text\">
403 <div class=\"group_field\" id=\"%s_group_field\">",
412 $this->openGroupByIdContent($groupId, $content);
414 // Is a sub group opened?
415 if ($this->ifSubGroupOpenedPreviously()) {
417 $this->addFormSubGroup();
420 // Get previous group id
421 $prevGroupId = $this->getPreviousGroupId();
424 $this->closePreviousGroupByContent($content);
426 // All call it again if the group name is not empty
427 if ((!empty($groupId)) && ($groupId != $prevGroupId)) {
428 //* DEBUG: */ echo $groupId."/".$prevGroupId."<br />\n";
429 $this->addFormGroup($groupId, $groupText);
435 * Add a form sub group or close an already opened and open a new one or
436 * throws an exception if no group has been opened before or if the sub
437 * group name is empty.
439 * @param $subGroupId Name of the group or last opened if empty
440 * @param $subGroupText Text including HTML to show above this group
442 * @throws FormFormClosedException If no group has been opened before
443 * @throws EmptyVariableException If $subGroupId is not set
445 public function addFormSubGroup ($subGroupId = "", $subGroupText = "") {
446 // Is a group opened?
447 if (!$this->ifGroupOpenedPreviously()) {
448 // Throw exception here
449 throw new FormFormClosedException(array($this, $subGroupId), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
452 // At least the sub group name should be set
453 if ((empty($subGroupId)) && (!$this->ifSubGroupOpenedPreviously())) {
454 // Throw exception here
455 throw new EmptyVariableException(array($this, 'subGroupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
456 } elseif (empty($subGroupId)) {
457 // Close the last opened
458 $subGroupId = $this->getPreviousSubGroupId();
461 // Same sub group to open?
462 if ((!$this->ifSubGroupOpenedPreviously()) && ($subGroupId == $this->getPreviousSubGroupId())) {
463 // Abort here silently
467 // Initialize content with closing div by default
468 $content = " </div>\n</div><!-- Sub group- CLOSE //-->";
470 // Is this group opened?
471 if (!$this->ifSubGroupOpenedPreviously()) {
472 // Begin the span block
473 $content = sprintf("<!-- Sub group %s - OPEN //-->
474 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
475 <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
478 <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
486 // Switch the state and remeber the name
487 $this->openSubGroupByIdContent($subGroupId, $content);
489 // Get previous sub group id
490 $prevSubGroupId = $this->getPreviousSubGroupId();
493 $this->closePreviousSubGroupByContent($content);
495 // All call it again if sub group name is not empty
496 if ((!empty($subGroupId)) && ($subGroupId != $prevSubGroupId)) {
497 $this->addFormSubGroup($subGroupId, $subGroupText);
503 * Add text surrounded by a span block when there is a group opened before
504 * or else by a div block.
506 * @param $fieldName Field name
507 * @param $fieldText Text for the field
509 * @throws FormClosedException If the form is not yet opened
511 public function addFieldText ($fieldName, $fieldText) {
512 // Is the form opened?
513 if (($this->formOpened === false) && ($this->formEnabled === true)) {
514 // Throw an exception
515 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
518 // Set the block type
520 if ($this->ifGroupOpenedPreviously()) $block = "span";
522 // Generate the content
523 $inputContent = sprintf(" <%s id=\"%s_text\">
533 $this->addContent($inputContent);
537 * Add text (notes) surrounded by a div block. Still opened groups or sub
538 * groups will be automatically closed.
540 * @param $noteId Id for this note
541 * @param $formNotes The form notes we shell addd
543 * @throws FormClosedException If the form is not yet opened
545 public function addFormNote ($noteId, $formNotes) {
546 // Is the form opened?
547 if (($this->formOpened === false) && ($this->formEnabled === true)) {
548 // Throw an exception
549 throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
553 if ($this->ifGroupOpenedPreviously()) {
554 // Then automatically close it here
555 $this->addFormGroup();
558 // Generate the content
559 $inputContent = sprintf(" <div id=\"form_note_%s\">
567 $this->addContent($inputContent);
571 * Checks wether the registration requires a valid email address
573 * @return $required Wether the email address is required
575 public function ifRegisterRequiresEmailVerification () {
576 $required = ($this->getConfigInstance()->readConfig('register_requires_email') === "Y");
581 * Checks wether profile data shall be asked
583 * @return $required Wether profile shall be asked
585 public function ifRegisterIncludesProfile () {
586 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') === "Y");
591 * Adds a pre-configured CAPTCHA
595 public function addCaptcha () {
596 // Get last executed pre filter
597 $extraInstance = Registry::getRegistry()->getInstance('extra');
599 // Get a configured instance
600 $captchaInstance = ObjectFactory::createObjectByConfiguredName($this->getFormName().'_captcha', array($this, $extraInstance));
602 // Initiate the CAPTCHA
603 $captchaInstance->initiateCaptcha();
605 // Render the CAPTCHA code
606 $captchaInstance->renderCode();
608 // Get the content and add it to the helper
609 $this->addContent($captchaInstance->renderContent());
613 * Enables/disables the form tag usage
615 * @param $formEnabled Wether form is enabled or disabled
618 public final function enableForm ($formEnabled = true) {
619 $this->formEnabled = (bool) $formEnabled;
623 * Setter for form name
625 * @param $formName Name of this form
628 public final function setFormName ($formName) {
629 $this->formName = (string) $formName;
633 * Getter for form name
635 * @return $formName Name of this form
637 public final function getFormName () {
638 return $this->formName;
642 * Checks wether this form is secured by a CAPTCHA
644 * @return $isSecured Wether this form is secured by a CAPTCHA
646 public function ifFormSecuredWithCaptcha () {
647 $isSecured = ($this->getConfigInstance()->readConfig($this->getFormName().'_captcha_secured') === "Y");
652 * Flushs the content out (not yet secured against open forms, etc.!) or
653 * close the form automatically
656 * @throws FormOpenedException If the form is still open
658 public function flushContent () {
659 // Is the form still open?
660 if (($this->formOpened === true) && ($this->formEnabled === true)) {
661 // Close the form automatically
663 } elseif ($this->formEnabled === false) {
664 if ($this->ifSubGroupOpenedPreviously()) {
666 $this->addFormSubGroup();
667 } elseif ($this->ifGroupOpenedPreviously()) {
669 $this->addFormGroup();
673 // Send content to template engine
674 //* DEBUG: */ echo __METHOD__.": form=".$this->getFormName().", size=".strlen($this->renderContent())."<br />\n";
675 $this->getTemplateInstance()->assignVariable($this->getFormName(), $this->renderContent());