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 * 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;
47 * Name of the sub group
49 private $subGroupName = "";
52 const EXCEPTION_FORM_NAME_INVALID = 0x030;
53 const EXCEPTION_CLOSED_FORM = 0x031;
54 const EXCEPTION_OPENED_FORM = 0x032;
55 const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x033;
58 * Protected constructor
62 protected function __construct () {
63 // Call parent constructor
64 parent::__construct(__CLASS__);
66 // Set part description
67 $this->setObjectDescription("Helper class for HTML forms");
69 // Create unique ID number
70 $this->generateUniqueId();
74 * Creates the helper class with the given template engine instance and form name
76 * @param $templateInstance An instance of a valid template engine
77 * @param $formName Name of the form
78 * @param $formId Value for "id" attribute (default: $formName)
79 * @return $helperInstance A preparedf instance of this class
81 public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) {
83 $helperInstance = new WebFormHelper();
85 // Set template instance
86 $helperInstance->setTemplateInstance($templateInstance);
88 // Is the form id not set?
89 if ($formId === false) {
90 // Use form id from form name
95 $helperInstance->addFormTag($formName, $formId);
97 // Return the prepared instance
98 return $helperInstance;
102 * Add the form tag or close it an already opened form tag
104 * @param $formName Name of the form (default: false)
105 * @param $formId Id of the form (attribute "id"; default: false)
107 * @throws InvalidFormNameException If the form name is invalid (=false)
109 public function addFormTag ($formName = false, $formId = false) {
110 // When the form is not yet opened at least form name must be valid
111 if (($this->formOpened === false) && ($formName === false)) {
112 // Thrown an exception
113 throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
116 // Close the form is default
117 $formContent = "</form>";
119 // Check wether we shall open or close the form
120 if ($this->formOpened === false) {
122 $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s/%s\" method=\"%s\" target=\"%s\"",
124 $this->getConfigInstance()->readConfig('base_url'),
125 $this->getConfigInstance()->readConfig('form_action'),
126 $this->getConfigInstance()->readConfig('form_method'),
127 $this->getConfigInstance()->readConfig('form_target')
130 // Is the form id set?
131 if ($formId !== false) {
132 // Then add it as well
133 $formContent .= sprintf(" id=\"%s_form\"",
141 // Open the form and remeber the form name
142 $this->formOpened = true;
143 $this->formName = $formName;
145 // Add the hidden field required to identify safely this form
146 $this->addInputHiddenField('form', $this->formName);
149 if ($this->groupOpened === true) {
150 // Then automatically close it here
151 $this->addFormGroup("", "");
154 // @TODO Add some unique PIN here to bypass problems with some browser and/or extensions
156 $this->formOpened = false;
159 // Add it to the content
160 $this->addContent($formContent);
164 * Add a text input tag to the form or throw an exception if it is not yet
165 * opened. The field's name will be set as id.
167 * @param $fieldName Input field name
168 * @param $fieldValue Input default value (default: empty)
170 * @throws FormClosedException If the form is not yet opened
172 public function addInputTextField ($fieldName, $fieldValue = "") {
173 // Is the form opened?
174 if ($this->formOpened === false) {
175 // Throw an exception
176 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
179 // Generate the content
180 $inputContent = sprintf("<input type=\"text\" class=\"textfield\" id=\"%s\" name=\"%s\" value=\"%s\" />",
186 // And add it maybe with a "li" tag
187 $this->addContent($inputContent);
191 * Add a password input tag to the form or throw an exception if it is not
192 * yet opened. The field's name will be set as id.
194 * @param $fieldName Input field name
195 * @param $fieldValue Input default value (default: empty)
197 * @throws FormClosedException If the form is not yet opened
199 public function addInputPasswordField ($fieldName, $fieldValue = "") {
200 // Is the form opened?
201 if ($this->formOpened === false) {
202 // Throw an exception
203 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
206 // Generate the content
207 $inputContent = sprintf("<input type=\"password\" class=\"password\" id=\"%s\" name=\"%s\" value=\"%s\" />",
214 $this->addContent($inputContent);
218 * Add a hidden input tag to the form or throw an exception if it is not
219 * yet opened. The field's name will be set as id.
221 * @param $fieldName Input field name
222 * @param $fieldValue Input default value (default: empty)
224 * @throws FormClosedException If the form is not yet opened
226 public function addInputHiddenField ($fieldName, $fieldValue = "") {
227 // Is the form opened?
228 if ($this->formOpened === false) {
229 // Throw an exception
230 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
233 // Generate the content
234 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
240 $this->addContent($inputContent);
244 * Add a checkbox input tag to the form or throw an exception if it is not
245 * yet opened. The field's name will be set as id.
247 * @param $fieldName Input field name
248 * @param $fieldChecked Wether the field is checked (defaut: checked)
250 * @throws FormClosedException If the form is not yet opened
252 public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
253 // Is the form opened?
254 if ($this->formOpened === false) {
255 // Throw an exception
256 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
259 // Set wether the check box is checked...
260 $checked = " checked=\"checked\"";
261 if ($fieldChecked === false) $checked = " ";
263 // Generate the content
264 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox\" id=\"%s\" value=\"1\"%s/>",
271 $this->addContent($inputContent);
275 * Add a reset input tag to the form or throw an exception if it is not
276 * yet opened. The field's name will be set as id.
278 * @param $buttonText Text displayed on the button
280 * @throws FormClosedException If the form is not yet opened
282 public function addInputResetButton ($buttonText) {
283 // Is the form opened?
284 if ($this->formOpened === false) {
285 // Throw an exception
286 throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
289 // Generate the content
290 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
296 $this->addContent($inputContent);
300 * Add a reset input tag to the form or throw an exception if it is not
301 * yet opened. The field's name will be set as id.
303 * @param $buttonText Text displayed on the button
305 * @throws FormClosedException If the form is not yet opened
307 public function addInputSubmitButton ($buttonText) {
308 // Is the form opened?
309 if ($this->formOpened === false) {
310 // Throw an exception
311 throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
314 // Generate the content
315 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
322 $this->addContent($inputContent);
326 * Add a form group or close an already opened and open a new one
328 * @param $groupName Name of the group
329 * @param $groupText Text including HTML to show above this group
331 * @throws FormClosedException If no form has been opened before
332 * @throws EmptyVariableException If $groupName is not set
334 public function addFormGroup ($groupName, $groupText) {
336 if ($this->formOpened === false) {
337 // Throw exception here
338 throw new FormClosedException(array($this, $groupName), self::EXCEPTION_CLOSED_FORM);
341 // At least the group name should be set
342 if ((empty($groupName)) && ($this->groupOpened === false)) {
343 // Throw exception here
344 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
347 // Initialize content with closing div by default
348 $content = " </div>\n</div><!-- Group - CLOSE //-->";
350 // Is this group opened?
351 if ($this->groupOpened === false) {
352 // Begin the div/span blocks
353 $content = sprintf("<!-- Group %s - OPEN //-->
354 <div class=\"group_box\" id=\"%s_group_box\">
355 <span class=\"group_text\" id=\"%s_group_text\">
358 <div class=\"group_field\" id=\"%s_group_field\">",
367 $this->addContent($content);
370 $this->groupOpened = true;
372 // Is a sub group opened?
373 if ($this->subGroupOpened === true) {
375 $this->addFormSubGroup("", "");
379 $this->addContent($content);
382 $this->groupOpened = false;
384 // All call it again if the group name is not empty
385 if (!empty($groupName)) {
386 $this->addFormGroup($groupName, $groupText);
392 * Add a form sub group or close an already opened and open a new one or
393 * throws an exception if no group has been opened before or if the sub
394 * group name is empty.
396 * @param $subGroupName Name of the group
397 * @param $subGroupText Text including HTML to show above this group
399 * @throws FormGroupClosedException If no group has been opened before
400 * @throws EmptyVariableException If $subGroupName is not set
402 public function addFormSubGroup ($subGroupName, $subGroupText) {
403 // Is a group opened?
404 if ($this->groupOpened === false) {
405 // Throw exception here
406 throw new FormGroupClosedException(array($this, $subGroupName), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
409 // At least the sub group name should be set
410 if ((empty($subGroupName)) && ($this->subGroupOpened === false)) {
411 // Throw exception here
412 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
415 // Initialize content with closing div by default
416 $content = " </div>\n</div><!-- Sub group- CLOSE //-->";
418 // Is this group opened?
419 if ($this->subGroupOpened === false) {
420 // Begin the span block
421 $content = sprintf("<!-- Sub group %s - OPEN //-->
422 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
423 <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
426 <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
435 $this->addContent($content);
437 // Switch the state and remeber the name
438 $this->subGroupOpened = true;
439 $this->subGroupName = $subGroupName;
442 $this->addContent($content);
445 $this->subGroupOpened = false;
447 // All call it again if sub group name is not empty
448 if (!empty($subGroupName)) {
449 $this->addFormSubGroup($subGroupName, $subGroupText);
455 * Add text surrounded by a span block when there is a group opened before
456 * or else by a div block.
458 * @param $fieldName Field name
459 * @param $fieldText Text for the field
461 * @throws FormClosedException If the form is not yet opened
463 public function addFieldText ($fieldName, $fieldText) {
464 // Is the form opened?
465 if ($this->formOpened === false) {
466 // Throw an exception
467 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
470 // Set the block type
472 if ($this->groupOpened === true) $block = "span";
474 // Generate the content
475 $inputContent = sprintf(" <%s id=\"%s_text\">
485 $this->addContent($inputContent);
489 * Add text (notes) surrounded by a div block. Still opened groups or sub
490 * groups will be automatically closed.
492 * @param $formNotes The form notes we shell addd
494 * @throws FormClosedException If the form is not yet opened
496 public function addFormNote ($formNotes) {
497 // Is the form opened?
498 if ($this->formOpened === false) {
499 // Throw an exception
500 throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
504 if ($this->groupOpened === true) {
505 // Then automatically close it here
506 $this->addFormGroup("unknown", "");
509 // Generate the content
510 $inputContent = sprintf(" <div id=\"form_note\">
517 $this->addContent($inputContent);
521 * Checks wether the registration requires a valid email address
523 * @return $required Wether the email address is required
525 public function ifRegisterRequiresEmailVerification () {
526 $required = ($this->getConfigInstance()->readConfig('register_requires_email') == "Y");
531 * Checks wether profile data shall be asked
533 * @return $required Wether profile shall be asked
535 public function ifRegisterIncludesProfile () {
536 $required = ($this->getConfigInstance()->readConfig('register_includes_profile') == "Y");
541 * Checks wether personal data shall be asked
543 * @return $required Wether personal data shall be asked
545 public function ifRegisterIncludesPersonaData () {
546 $required = ($this->getConfigInstance()->readConfig('register_personal_data') == "Y");
551 * Checks wether email addresses can only be once used
555 public function ifEmailMustBeUnique () {
556 $isUnique = ($this->getConfigInstance()->readConfig('register_email_unique') == "Y");
561 * Checks wether the specified chat protocol is enabled in this form
563 * @return $required Wether the specified chat protocol is enabled
565 public function ifChatEnabled ($chatProtocol) {
566 $required = ($this->getConfigInstance()->readConfig(sprintf("chat_enabled_%s", $chatProtocol)) == "Y");
571 * Flushs the content out (not yet secured against open forms, etc.!) or
572 * throw an exception if it is not yet closed
575 * @throws FormOpenedException If the form is still open
577 public function flushContent () {
578 // Is the form still open?
579 if ($this->formOpened === true) {
580 // Throw an exception
581 throw new FormOpenedException ($this, self::EXCEPTION_OPENED_FORM);
584 // Send content to template engine
585 $this->getTemplateInstance()->assignVariable($this->formName, $this->getContent());