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 = 0xb00;
53 const EXCEPTION_CLOSED_FORM = 0xb01;
54 const EXCEPTION_OPENED_FORM = 0xb02;
55 const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0xb03;
62 protected function __construct () {
63 // Call parent constructor
64 parent::__construct(__CLASS__);
66 // Set part description
67 $this->setObjectDescription("HTML-Formularhilfsklasse");
71 * Creates the helper class with the given template engine instance and form name
73 * @param $templateInstance An instance of a valid template engine
74 * @param $formName Name of the form
75 * @param $formId Value for "id" attribute (default: $formName)
76 * @return $helperInstance A preparedf instance of this class
78 public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) {
80 $helperInstance = new WebFormHelper();
82 // Set template instance
83 $helperInstance->setTemplateInstance($templateInstance);
85 // Is the form id not set?
86 if ($formId === false) {
87 // Use form id from form name
92 $helperInstance->addFormTag($formName, $formId);
94 // Return the prepared instance
95 return $helperInstance;
99 * Add the form tag or close it an already opened form tag
101 * @param $formName Name of the form (default: false)
102 * @param $formId Id of the form (attribute "id"; default: false)
104 * @throws InvalidFormNameException If the form name is invalid (=false)
106 public function addFormTag ($formName = false, $formId = false) {
107 // When the form is not yet opened at least form name must be valid
108 if (($this->formOpened === false) && ($formName === false)) {
109 // Thrown an exception
110 throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
113 // Close the form is default
114 $formContent = "</form>";
116 // Check wether we shall open or close the form
117 if ($this->formOpened === false) {
119 $formContent = sprintf("<form name=\"%s\" class=\"forms\" action=\"%s\" method=\"%s\" target=\"%s\"",
121 $this->getConfigInstance()->readConfig("form_action"),
122 $this->getConfigInstance()->readConfig("form_method"),
123 $this->getConfigInstance()->readConfig("form_target")
126 // Is the form id set?
127 if ($formId !== false) {
128 // Then add it as well
129 $formContent .= sprintf(" id=\"%s_form\"",
137 // Open the form and remeber the form name
138 $this->formOpened = true;
139 $this->formName = $formName;
141 // Add the hidden field required to identify safely this form
142 $this->addInputHiddenField("form", $this->formName);
145 if ($this->groupOpened === true) {
146 // Then automatically close it here
147 $this->addFormGroup("", "");
150 // @TODO Add some unique PIN here to bypass problems with some browser and/or extensions
152 $this->formOpened = false;
155 // Add it to the content
156 $this->addContent($formContent);
160 * Add a text input tag to the form or throw an exception if it is not yet
161 * opened. The field's name will be set as id.
163 * @param $fieldName Input field name
164 * @param $fieldValue Input default value (default: empty)
166 * @throws FormClosedException If the form is not yet opened
168 public function addInputTextField ($fieldName, $fieldValue = "") {
169 // Is the form opened?
170 if ($this->formOpened === false) {
171 // Throw an exception
172 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
175 // Generate the content
176 $inputContent = sprintf("<input type=\"text\" class=\"textfield\" id=\"%s\" name=\"%s\" value=\"%s\" />",
182 // And add it maybe with a "li" tag
183 $this->addContent($inputContent);
187 * Add a password input tag to the form or throw an exception if it is not
188 * yet 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 addInputPasswordField ($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=\"password\" class=\"password\" id=\"%s\" name=\"%s\" value=\"%s\" />",
210 $this->addContent($inputContent);
214 * Add a hidden input tag to the form or throw an exception if it is not
215 * yet opened. The field's name will be set as id.
217 * @param $fieldName Input field name
218 * @param $fieldValue Input default value (default: empty)
220 * @throws FormClosedException If the form is not yet opened
222 public function addInputHiddenField ($fieldName, $fieldValue = "") {
223 // Is the form opened?
224 if ($this->formOpened === false) {
225 // Throw an exception
226 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
229 // Generate the content
230 $inputContent = sprintf("<input type=\"hidden\" name=\"%s\" value=\"%s\" />",
236 $this->addContent($inputContent);
240 * Add a checkbox input tag to the form or throw an exception if it is not
241 * yet opened. The field's name will be set as id.
243 * @param $fieldName Input field name
244 * @param $fieldChecked Wether the field is checked (defaut: checked)
246 * @throws FormClosedException If the form is not yet opened
248 public function addInputCheckboxField ($fieldName, $fieldChecked = true) {
249 // Is the form opened?
250 if ($this->formOpened === false) {
251 // Throw an exception
252 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
255 // Set wether the check box is checked...
256 $checked = " checked=\"checked\"";
257 if ($fieldChecked === false) $checked = " ";
259 // Generate the content
260 $inputContent = sprintf("<input type=\"checkbox\" name=\"%s\" class=\"checkbox\" id=\"%s\" value=\"1\"%s/>",
267 $this->addContent($inputContent);
271 * Add a reset input tag to the form or throw an exception if it is not
272 * yet opened. The field's name will be set as id.
274 * @param $buttonText Text displayed on the button
276 * @throws FormClosedException If the form is not yet opened
278 public function addInputResetButton ($buttonText) {
279 // Is the form opened?
280 if ($this->formOpened === false) {
281 // Throw an exception
282 throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM);
285 // Generate the content
286 $inputContent = sprintf("<input type=\"reset\" class=\"reset_button\" id=\"%s_reset\" value=\"%s\" />",
292 $this->addContent($inputContent);
296 * Add a reset input tag to the form or throw an exception if it is not
297 * yet opened. The field's name will be set as id.
299 * @param $buttonText Text displayed on the button
301 * @throws FormClosedException If the form is not yet opened
303 public function addInputSubmitButton ($buttonText) {
304 // Is the form opened?
305 if ($this->formOpened === false) {
306 // Throw an exception
307 throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM);
310 // Generate the content
311 $inputContent = sprintf("<input type=\"submit\" class=\"submit_button\" id=\"%s_submit\" name=\"%s_button\" value=\"%s\" />",
318 $this->addContent($inputContent);
322 * Add a form group or close an already opened and open a new one
324 * @param $groupName Name of the group
325 * @param $groupText Text including HTML to show above this group
327 * @throws FormClosedException If no form has been opened before
328 * @throws EmptyVariableException If $groupName is not set
330 public function addFormGroup ($groupName, $groupText) {
332 if ($this->formOpened === false) {
333 // Throw exception here
334 throw new FormClosedException(array($this, $groupName), self::EXCEPTION_CLOSED_FORM);
337 // At least the group name should be set
338 if ((empty($groupName)) && ($this->groupOpened === false)) {
339 // Throw exception here
340 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
343 // Initialize content with closing div by default
344 $content = " </div>\n</div><!-- Group - CLOSE //-->";
346 // Is this group opened?
347 if ($this->groupOpened === false) {
348 // Begin the div/span blocks
349 $content = sprintf("<!-- Group %s - OPEN //-->
350 <div class=\"group_box\" id=\"%s_group_box\">
351 <span class=\"group_text\" id=\"%s_group_text\">
354 <div class=\"group_field\" id=\"%s_group_field\">",
363 $this->addContent($content);
366 $this->groupOpened = true;
368 // Is a sub group opened?
369 if ($this->subGroupOpened === true) {
371 $this->addFormSubGroup("", "");
375 $this->addContent($content);
378 $this->groupOpened = false;
380 // All call it again if the group name is not empty
381 if (!empty($groupName)) {
382 $this->addFormGroup($groupName, $groupText);
388 * Add a form sub group or close an already opened and open a new one or
389 * throws an exception if no group has been opened before or if the sub
390 * group name is empty.
392 * @param $subGroupName Name of the group
393 * @param $subGroupText Text including HTML to show above this group
395 * @throws FormGroupClosedException If no group has been opened before
396 * @throws EmptyVariableException If $subGroupName is not set
398 public function addFormSubGroup ($subGroupName, $subGroupText) {
399 // Is a group opened?
400 if ($this->groupOpened === false) {
401 // Throw exception here
402 throw new FormGroupClosedException(array($this, $subGroupName), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP);
405 // At least the sub group name should be set
406 if ((empty($subGroupName)) && ($this->subGroupOpened === false)) {
407 // Throw exception here
408 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
411 // Initialize content with closing div by default
412 $content = " </div>\n</div><!-- Sub group- CLOSE //-->";
414 // Is this group opened?
415 if ($this->subGroupOpened === false) {
416 // Begin the span block
417 $content = sprintf("<!-- Sub group %s - OPEN //-->
418 <div class=\"subgroup_box\" id=\"%s_subgroup_box\">
419 <span class=\"subgroup_text\" id=\"%s_subgroup_text\">
422 <div class=\"subgroup_field\" id=\"%s_subgroup_field\">",
431 $this->addContent($content);
433 // Switch the state and remeber the name
434 $this->subGroupOpened = true;
435 $this->subGroupName = $subGroupName;
438 $this->addContent($content);
441 $this->subGroupOpened = false;
443 // All call it again if sub group name is not empty
444 if (!empty($subGroupName)) {
445 $this->addFormSubGroup($subGroupName, $subGroupText);
451 * Add text surrounded by a span block when there is a group opened before
452 * or else by a div block.
454 * @param $fieldName Field name
455 * @param $fieldText Text for the field
457 * @throws FormClosedException If the form is not yet opened
459 public function addFieldText ($fieldName, $fieldText) {
460 // Is the form opened?
461 if ($this->formOpened === false) {
462 // Throw an exception
463 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
466 // Set the block type
468 if ($this->groupOpened === true) $block = "span";
470 // Generate the content
471 $inputContent = sprintf(" <%s id=\"%s_text\">
481 $this->addContent($inputContent);
485 * Add text (notes) surrounded by a div block. Still opened groups or sub
486 * groups will be automatically closed.
488 * @param $formNotes The form notes we shell addd
490 * @throws FormClosedException If the form is not yet opened
492 public function addFormNote ($formNotes) {
493 // Is the form opened?
494 if ($this->formOpened === false) {
495 // Throw an exception
496 throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM);
500 if ($this->groupOpened === true) {
501 // Then automatically close it here
502 $this->addFormGroup("unknown", "");
505 // Generate the content
506 $inputContent = sprintf(" <div id=\"form_note\">
513 $this->addContent($inputContent);
517 * Checks wether the registration requires a valid email address
519 * @return $required Wether the email address is required
521 public function ifRegisterRequiresEmailVerification () {
522 $required = ($this->getConfigInstance()->readConfig("register_requires_email") == "Y");
527 * Checks wether profile data shall be asked
529 * @return $required Wether profile shall be asked
531 public function ifRegisterIncludesProfile () {
532 $required = ($this->getConfigInstance()->readConfig("register_includes_profile") == "Y");
537 * Checks wether personal data shall be asked
539 * @return $required Wether personal data shall be asked
541 public function ifRegisterIncludesPersonaData () {
542 $required = ($this->getConfigInstance()->readConfig("register_personal_data") == "Y");
547 * Checks wether the specified chat protocol is enabled in this form
549 * @return $required Wether the specified chat protocol is enabled
551 public function ifChatEnabled ($chatProtocol) {
552 $required = ($this->getConfigInstance()->readConfig(sprintf("chat_enabled_%s", $chatProtocol)) == "Y");
557 * Flushs the content out (not yet secured against open forms, etc.!) or
558 * throw an exception if it is not yet closed
561 * @throws FormOpenedException If the form is still open
563 public function flushContent () {
564 // Is the form still open?
565 if ($this->formOpened === true) {
566 // Throw an exception
567 throw new FormOpenedException ($this, self::EXCEPTION_OPENED_FORM);
570 // Send content to template engine
571 $this->getTemplateInstance()->assignVariable($this->formName, $this->getContent());