3 * A helper for constructing HTML 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 HtmlFormHelper extends BaseTemplateHelper {
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 const EXCEPTION_FORM_NAME_INVALID = 0xb00;
48 const EXCEPTION_CLOSED_FORM = 0xb01;
49 const EXCEPTION_OPENED_FORM = 0xb02;
56 protected function __construct () {
57 // Call parent constructor
58 parent::__construct(__CLASS__);
60 // Set part description
61 $this->setObjectDescription("HTML-Formularhilfsklasse");
65 * Creates the helper class with the given template engine instance and form name
67 * @param $templateInstance An instance of a valid template engine
68 * @param $formName Name of the form
69 * @param $formId Value for "id" attribute (default: $formName)
70 * @return $helperInstance A preparedf instance of this class
72 public final static function createHtmlFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) {
74 $helperInstance = new HtmlFormHelper();
76 // Set template instance
77 $helperInstance->setTemplateInstance($templateInstance);
79 // Is the form id not set?
80 if ($formId === false) {
81 // Use form id from form name
86 $helperInstance->addFormTag($formName, $formId);
88 // Return the prepared instance
89 return $helperInstance;
93 * Add the form tag or close it an already opened form tag
95 * @param $formName Name of the form (default: false)
96 * @param $formId Id of the form (attribute "id"; default: false)
98 * @throws InvalidFormNameException If the form name is invalid (=false)
100 public function addFormTag ($formName = false, $formId = false) {
101 // When the form is not yet opened at least form name must be valid
102 if ((!$this->formOpened) && ($formName === false)) {
103 // Thrown an exception
104 throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
107 // Close the form is default
108 $formContent = "</form>";
110 // Check wether we shall open or close the form
111 if (!$this->formOpened) {
113 $formContent = sprintf("<form name=\"%s\" action=\"%s\" method=\"%s\" target=\"%s\"",
115 $this->getConfigInstance()->readConfig("form_action"),
116 $this->getConfigInstance()->readConfig("form_method"),
117 $this->getConfigInstance()->readConfig("form_target")
120 // Is the form id set?
121 if ($formId !== false) {
122 // Then add it as well
123 $formContent .= sprintf(" id=\"%s\"",
131 // Open the form and remeber the form name
132 $this->formOpened = true;
133 $this->formName = $formName;
135 // Add the hidden field required to identify safely this form
136 $this->addInputHiddenField("form", $this->formName);
138 // @TODO Add some unique PIN here to bypass problems with some browser and/or extensions
140 $this->formOpened = false;
143 // Add it to the content
144 $this->addContent($formContent);
148 * Add an input tag to the form or throw an exception if it is not yet
149 * opened. The field's name will be set as id.
151 * @param $fieldName Input field name
152 * @param $fieldSize Input size
153 * @param $fieldMaxLength Input max length
154 * @param $fieldValue Input default value (default: empty)
156 * @throws FormClosedException If the form is not yet opened
158 public function addInputTextField ($fieldName, $fieldSize, $fieldMaxLength, $fieldValue = "") {
159 // Is the form opened?
160 if (!$this->formOpened) {
161 // Throw an exception
162 throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
165 // Generate the content
166 $inputContent = sprintf("<input type=\"text\" id=\"%s\" name=\"%s\" size=\"%d\" maxlength=\"%d\" value=\"%s\" />",
167 $fieldName, $fieldName, $fieldSize, $fieldMaxLength, $fieldValue);
170 $this->addContent($inputContent);
174 * Flushs the content out (not yet secured against open forms, etc.!) or
175 * throw an exception if it is not yet closed
178 * @throws FormOpenedException If the form is still open
180 public function flushContent () {
181 // Is the form opened?
182 if ($this->formOpened) {
183 // Throw an exception
184 throw new FormOpenedException ($this, self::EXCEPTION_OPENED_FORM);
187 // Send content to template engine
188 $this->getTemplateInstance()->assignVariable($this->formName, $this->getContent());
192 * Add a form group or close an already opened and open a new one
194 * @param $groupName Name of the group
195 * @param $groupText Text including HTML to show above this group
197 * @throws EmptyVariableException If $groupName is not set
199 public function addFormGroup ($groupName, $groupText) {
200 // At least the group name should be set
201 if (empty($groupName)) {
202 // Throw exception here
203 throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
206 // Not fully finished!
207 $this->partialStub(__METHOD__);
209 // Is this group opened?
210 if (!$this->groupOpened) {
212 $this->groupOpened = true;
215 $this->groupOpened = false;
218 $this->addFormGroup($groupName, $groupText);