00001 <?php
00002 /* SVN FILE: $Id: form_8php-source.html 675 2008-12-26 00:27:14Z gwoo $ */
00003 /**
00004  * Automatic generation of HTML FORMs from given data.
00005  *
00006  * Used for scaffolding.
00007  *
00008  * PHP versions 4 and 5
00009  *
00010  * CakePHP(tm) :  Rapid Development Framework <http://www.cakephp.org/>
00011  * Copyright 2005-2008, Cake Software Foundation, Inc.
00012  *                              1785 E. Sahara Avenue, Suite 490-204
00013  *                              Las Vegas, Nevada 89104
00014  *
00015  * Licensed under The MIT License
00016  * Redistributions of files must retain the above copyright notice.
00017  *
00018  * @filesource
00019  * @copyright       Copyright 2005-2008, Cake Software Foundation, Inc.
00020  * @link                http://www.cakefoundation.org/projects/info/cakephp CakePHP(tm) Project
00021  * @package         cake
00022  * @subpackage      cake.cake.libs.view.helpers
00023  * @since           CakePHP(tm) v 0.10.0.1076
00024  * @version         $Revision: 675 $
00025  * @modifiedby      $LastChangedBy: gwoo $
00026  * @lastmodified    $Date: 2008-12-25 16:27:14 -0800 (Thu, 25 Dec 2008) $
00027  * @license         http://www.opensource.org/licenses/mit-license.php The MIT License
00028  */
00029 /**
00030  * Tag template for a div with a class attribute.
00031  */
00032     define('TAG_DIV', '<div class="%s">%s</div>');
00033 /**
00034  * Tag template for a paragraph with a class attribute.
00035  */
00036     define('TAG_P_CLASS', '<p class="%s">%s</p>');
00037 /**
00038  * Tag template for a label with a for attribute.
00039  */
00040     define('TAG_LABEL', '<label for="%s">%s</label>');
00041 /**
00042  * Tag template for a fieldset with a legend tag inside.
00043  */
00044     define('TAG_FIELDSET', '<fieldset><legend>%s</legend>%s</label>');
00045 /**
00046  * Form helper library.
00047  *
00048  * Automatic generation of HTML FORMs from given data.
00049  *
00050  * @package     cake
00051  * @subpackage  cake.cake.libs.view.helpers
00052  */
00053 class FormHelper extends Helper{
00054 /**
00055  * Included helpers.
00056  *
00057  * @var array
00058  * @access public
00059  */
00060     var $helpers = array('Html');
00061 /**
00062  * Returns a formatted error message for given FORM field, NULL if no errors.
00063  *
00064  * @param string $field This should be "Modelname/fieldname"
00065  * @return bool If there are errors this method returns true, else false.
00066  * @access public
00067  */
00068     function isFieldError($field) {
00069         $error=1;
00070         $this->Html->setFormTag($field);
00071 
00072         if ($error == $this->Html->tagIsInvalid($this->Html->model, $this->Html->field)) {
00073             return true;
00074         } else {
00075             return false;
00076         }
00077     }
00078 /**
00079  * Returns a formatted LABEL element for HTML FORMs.
00080  *
00081  * @param string $tagName This should be "Modelname/fieldname"
00082  * @param string $text Text that will appear in the label field.
00083  * @return string The formatted LABEL element
00084  * @access public
00085  */
00086     function labelTag($tagName, $text) {
00087         return sprintf(TAG_LABEL, Inflector::camelize(str_replace('/', '_', $tagName)), $text);
00088     }
00089 /**
00090  * Returns a formatted DIV tag for HTML FORMs.
00091  *
00092  * @param string $class CSS class name of the div element.
00093  * @param string $text String content that will appear inside the div element.
00094  * @return string The formatted DIV element
00095  * @access public
00096  */
00097     function divTag($class, $text) {
00098         return sprintf(TAG_DIV, $class, $text);
00099     }
00100 /**
00101  * Returns a formatted P tag with class for HTML FORMs.
00102  *
00103  * @param string $class CSS class name of the p element.
00104  * @param string $text Text that will appear inside the p element.
00105  * @return string The formatted P element
00106  * @access public
00107  */
00108     function pTag($class, $text) {
00109         return sprintf(TAG_P_CLASS, $class, $text);
00110     }
00111 /**
00112  * Returns a formatted INPUT tag for HTML FORMs.
00113  *
00114  * @param string $tagName   This should be "Modelname/fieldname"
00115  * @param string $prompt Text that will appear in the label field.
00116  * @param bool $required True if this field is a required field.
00117  * @param string $errorMsg  Text that will appear if an error has occurred.
00118  * @param int $size Size attribute for INPUT element
00119  * @param array $htmlOptions    HTML options array.
00120  * @return string The formatted INPUT element, with a label and wrapped in a div.
00121  * @access public
00122  */
00123     function generateInputDiv($tagName, $prompt, $required = false, $errorMsg = null, $size = 20, $htmlOptions = null) {
00124         $htmlAttributes = $htmlOptions;
00125         $htmlAttributes['size'] = $size;
00126         $str = $this->Html->input($tagName, $htmlAttributes);
00127         $strLabel = $this->labelTag($tagName, $prompt);
00128         $divClass = "optional";
00129         if ($required) {
00130             $divClass = "required";
00131         }
00132         $strError = "";
00133 
00134         if ($this->isFieldError($tagName)) {
00135             $strError = $this->pTag('error', $errorMsg);
00136             $divClass = sprintf("%s error", $divClass);
00137         }
00138         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00139         return $this->divTag($divClass, $divTagInside);
00140     }
00141 /**
00142  * Returns a formatted CHECKBOX tag inside a DIV for HTML FORMs.
00143  *
00144  * @param string $tagName This should be "Modelname/fieldname"
00145  * @param string $prompt Text that will appear in the label field.
00146  * @param bool $required True if this field is a required field.
00147  * @param string $errorMsg Text that will appear if an error has occurred.
00148  * @param array $htmlOptions    HTML options array.
00149  * @return string The formatted checkbox div
00150  * @access public
00151  */
00152     function generateCheckboxDiv($tagName, $prompt, $required = false, $errorMsg = null, $htmlOptions = null) {
00153         $htmlOptions['class'] = "inputCheckbox";
00154         $str = $this->Html->checkbox($tagName, null, $htmlOptions);
00155         $strLabel = $this->labelTag($tagName, $prompt);
00156         $divClass = "optional";
00157         if ($required) {
00158             $divClass = "required";
00159         }
00160         $strError = "";
00161 
00162         if ($this->isFieldError($tagName)) {
00163             $strError = $this->pTag('error', $errorMsg);
00164             $divClass = sprintf("%s error", $divClass);
00165         }
00166         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00167         return $this->divTag($divClass, $divTagInside);
00168     }
00169 /**
00170  * Returns a formatted date option element for HTML FORMs.
00171  *
00172  * @param string $tagName   This should be "Modelname/fieldname"
00173  * @param string $prompt Text that will appear in the label field.
00174  * @param bool $required True if this field is a required field.
00175  * @param string $errorMsg  Text that will appear if an error has occurred.
00176  * @param int $size Not used.
00177  * @param array $htmlOptions HTML options array
00178  * @return string Date option wrapped in a div.
00179  * @todo  Remove the $size parameter from this method.
00180  * @access public
00181  */
00182     function generateDate($tagName, $prompt, $required = false, $errorMsg = null, $size = 20, $htmlOptions = null, $selected = null) {
00183         $str = $this->Html->dateTimeOptionTag($tagName, 'MDY', 'NONE', $selected, $htmlOptions);
00184         $strLabel = $this->labelTag($tagName, $prompt);
00185         $divClass = "optional";
00186         if ($required) {
00187             $divClass = "required";
00188         }
00189         $strError = "";
00190 
00191         if ($this->isFieldError($tagName)) {
00192             $strError = $this->pTag('error', $errorMsg);
00193             $divClass = sprintf("%s error", $divClass);
00194         }
00195         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00196         $requiredDiv = $this->divTag($divClass, $divTagInside);
00197         return $this->divTag("date", $requiredDiv);
00198     }
00199 /**
00200  * Returns a formatted date option element for HTML FORMs.
00201  *
00202  * @param string $tagName   This should be "Modelname/fieldname"
00203  * @param string $prompt Text that will appear in the label field.
00204  * @param bool $required True if this field is a required field.
00205  * @param string $errorMsg  Text that will appear if an error has occurred.
00206  * @param int $size Not used.
00207  * @param array $htmlOptions HTML options array
00208  * @return string Date option wrapped in a div.
00209  * @todo  Remove the $size parameter from this method.
00210  * @access public
00211  */
00212     function generateTime($tagName, $prompt, $required = false, $errorMsg = null, $size = 20, $htmlOptions = null, $selected = null) {
00213         $str = $this->Html->dateTimeOptionTag($tagName, 'NONE', '24', $selected, $htmlOptions);
00214         $strLabel = $this->labelTag($tagName, $prompt);
00215         $divClass = "optional";
00216         if ($required) {
00217             $divClass = "required";
00218         }
00219         $strError = "";
00220 
00221         if ($this->isFieldError($tagName)) {
00222             $strError = $this->pTag('error', $errorMsg);
00223             $divClass = sprintf("%s error", $divClass);
00224         }
00225         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00226         $requiredDiv = $this->divTag($divClass, $divTagInside);
00227         return $this->divTag("time", $requiredDiv);
00228     }
00229 /**
00230  * Returns a formatted year option element for HTML FORMs.
00231  *
00232  * @param string $tagName   This should be "Modelname/fieldname"
00233  * @param string $prompt Text that will appear in the label field.
00234  * @param bool $required True if this field is a required field.
00235  * @param string $errorMsg  Text that will appear if an error has occurred.
00236  * @param int $size Not used.
00237  * @param array $htmlOptions HTML options array
00238  * @return string Date option wrapped in a div.
00239  * @todo  Remove the $size parameter from this method.
00240  * @access public
00241  */
00242     function generateYear($tagName, $prompt, $required = false, $errorMsg = null, $size = 20, $htmlOptions = null, $selected = null) {
00243         $str = $this->Html->dateTimeOptionTag($tagName, 'Y', 'NONE', $selected, $htmlOptions);
00244         $strLabel = $this->labelTag($tagName, $prompt);
00245         $divClass = "optional";
00246         if ($required) {
00247             $divClass = "required";
00248         }
00249         $strError = "";
00250 
00251         if ($this->isFieldError($tagName)) {
00252             $strError = $this->pTag('error', $errorMsg);
00253             $divClass = sprintf("%s error", $divClass);
00254         }
00255         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00256         $requiredDiv = $this->divTag($divClass, $divTagInside);
00257         return $this->divTag("year", $requiredDiv);
00258     }
00259 /**
00260  * Returns a formatted datetime option element for HTML FORMs.
00261  *
00262  * @param string $tagName This should be "Modelname/fieldname"
00263  * @param string $prompt Text that will appear in the label field.
00264  * @param bool $required True if this field is required.
00265  * @param string $errorMsg Text that will appear if an error has occurred.
00266  * @param int $size Not used.
00267  * @param array $htmlOptions  HTML options array
00268  * @param array $selected Selected index in the dateTimeOption tag.
00269  * @return string The formatted datetime option element wrapped in a div.
00270  * @todo  Remove the $size parameter from this method.
00271  * @access public
00272  */
00273     function generateDateTime($tagName, $prompt, $required = false, $errorMsg = null, $size = 20, $htmlOptions = null, $selected = null) {
00274         $str = $this->Html->dateTimeOptionTag($tagName, 'MDY', '12', $selected, $htmlOptions);
00275         $strLabel = $this->labelTag($tagName, $prompt);
00276         $divClass = "optional";
00277         if ($required) {
00278             $divClass = "required";
00279         }
00280         $strError = "";
00281 
00282         if ($this->isFieldError($tagName)) {
00283             $strError = $this->pTag('error', $errorMsg);
00284             $divClass = sprintf("%s error", $divClass);
00285         }
00286         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00287         $requiredDiv = $this->divTag($divClass, $divTagInside);
00288         return $this->divTag("date", $requiredDiv);
00289     }
00290 /**
00291  * Returns a formatted TEXTAREA inside a DIV for use with HTML forms.
00292  *
00293  * @param string $tagName   This should be "Modelname/fieldname"
00294  * @param string $prompt    Text that will appear in the label field.
00295  * @param boolean $required True if this field is required.
00296  * @param string $errorMsg  ext that will appear if an error has occurred.
00297  * @param integer $cols     Number of columns.
00298  * @param integer $rows     Number of rows.
00299  * @param array $htmlOptions    HTML options array.
00300  * @return string The formatted TEXTAREA element, wrapped in a div.
00301  * @access public
00302  */
00303     function generateAreaDiv($tagName, $prompt, $required = false, $errorMsg = null, $cols = 60, $rows = 10, $htmlOptions = null) {
00304         $htmlAttributes = $htmlOptions;
00305         $htmlAttributes['cols'] = $cols;
00306         $htmlAttributes['rows'] = $rows;
00307         $str = $this->Html->textarea($tagName, $htmlAttributes);
00308         $strLabel = $this->labelTag($tagName, $prompt);
00309         $divClass = "optional";
00310 
00311         if ($required) {
00312             $divClass="required";
00313         }
00314         $strError = "";
00315 
00316         if ($this->isFieldError($tagName)) {
00317             $strError = $this->pTag('error', $errorMsg);
00318             $divClass = sprintf("%s error", $divClass);
00319         }
00320         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00321         return $this->divTag($divClass, $divTagInside);
00322     }
00323 /**
00324  * Returns a formatted SELECT tag for HTML FORMs.
00325  *
00326  * @param string $tagName This should be "Modelname/fieldname"
00327  * @param string $prompt Text that will appear in the label field
00328  * @param array $options Options to be contained in SELECT element
00329  * @param string $selected Currently selected item
00330  * @param array $selectAttr Array of HTML attributes for the SELECT element
00331  * @param array $optionAttr Array of HTML attributes for the OPTION elements
00332  * @param bool $required True if this field is required
00333  * @param string $errorMsg Text that will appear if an error has occurred
00334  * @return string The formatted INPUT element, wrapped in a div
00335  * @access public
00336  */
00337     function generateSelectDiv($tagName, $prompt, $options, $selected = null, $selectAttr = null, $optionAttr = null, $required = false, $errorMsg = null) {
00338         $str = $this->Html->selectTag($tagName, $options, $selected, $selectAttr, $optionAttr);
00339         $strLabel = $this->labelTag($tagName, $prompt);
00340         $divClass = "optional";
00341 
00342         if ($required) {
00343             $divClass = "required";
00344         }
00345         $strError = "";
00346 
00347         if ($this->isFieldError($tagName)) {
00348             $strError=$this->pTag('error', $errorMsg);
00349             $divClass=sprintf("%s error", $divClass);
00350         }
00351         $divTagInside = sprintf("%s %s %s", $strError, $strLabel, $str);
00352         return $this->divTag($divClass, $divTagInside);
00353     }
00354 /**
00355  * Returns a formatted submit widget for HTML FORMs.
00356  *
00357  * @param string $displayText Text that will appear on the widget
00358  * @param array $htmlOptions HTML options array
00359  * @return string The formatted submit widget
00360  * @access public
00361  */
00362     function generateSubmitDiv($displayText, $htmlOptions = null) {
00363         return $this->divTag('submit', $this->Html->submit($displayText, $htmlOptions));
00364     }
00365 /**
00366  * Generates a form to go onto a HtmlHelper object.
00367  *
00368  * @param array $fields An array of form field definitions
00369  * @param boolean $readOnly True if the form should be rendered as READONLY
00370  * @return string The completed form specified by the $fields parameter
00371  * @access public
00372  */
00373     function generateFields($fields, $readOnly = false) {
00374         $strFormFields = '';
00375 
00376         foreach ($fields as $field) {
00377             if (isset($field['type'])) {
00378 
00379                 if (!isset($field['required'])) {
00380                     $field['required'] = false;
00381                 }
00382 
00383                 if (!isset($field['errorMsg'])) {
00384                     $field['errorMsg'] = null;
00385                 }
00386 
00387                 if (!isset($field['htmlOptions'])) {
00388                     $field['htmlOptions'] = array();
00389                 }
00390 
00391                 if ($readOnly) {
00392                     $field['htmlOptions']['READONLY'] = "readonly";
00393                 }
00394 
00395                 switch($field['type']) {
00396                     case "input":
00397                         if (!isset($field['size'])) {
00398                             $field['size'] = 40;
00399                         }
00400                         $strFormFields = $strFormFields . $this->generateInputDiv($field['tagName'], $field['prompt'],
00401                                                                         $field['required'], $field['errorMsg'], $field['size'], $field['htmlOptions']);
00402                     break;
00403                     case "checkbox":
00404                         $strFormFields = $strFormFields . $this->generateCheckboxDiv($field['tagName'], $field['prompt'],
00405                                                                         $field['required'], $field['errorMsg'], $field['htmlOptions']);
00406                     break;
00407                     case "select":
00408                     case "selectMultiple":
00409                         if ("selectMultiple" == $field['type']) {
00410                             $field['selectAttr']['multiple'] = 'multiple';
00411                             $field['selectAttr']['class'] = 'selectMultiple';
00412                         }
00413 
00414                         if (!isset($field['selected'])) {
00415                             $field['selected'] = null;
00416                         }
00417 
00418                         if (!isset($field['selectAttr'])) {
00419                             $field['selectAttr'] = null;
00420                         }
00421 
00422                         if (!isset($field['optionsAttr'])) {
00423                             $field['optionsAttr'] = null;
00424                         }
00425 
00426                         if ($readOnly) {
00427                             $field['selectAttr']['DISABLED'] = true;
00428                         }
00429 
00430                         if (!isset($field['options'])) {
00431                             $field['options'] = null;
00432                         }
00433                         $strFormFields = $strFormFields . $this->generateSelectDiv($field['tagName'], $field['prompt'], $field['options'],
00434                                                                         $field['selected'], $field['selectAttr'], $field['optionsAttr'], $field['required'], $field['errorMsg']);
00435                     break;
00436                     case "area":
00437                         if (!isset($field['rows'])) {
00438                             $field['rows'] = 10;
00439                         }
00440 
00441                         if (!isset($field['cols'])) {
00442                             $field['cols'] = 60;
00443                         }
00444                         $strFormFields = $strFormFields . $this->generateAreaDiv($field['tagName'], $field['prompt'],
00445                                                                         $field['required'], $field['errorMsg'], $field['cols'], $field['rows'], $field['htmlOptions']);
00446                     break;
00447                     case "fieldset":
00448                         $strFieldsetFields = $this->generateFields($field['fields']);
00449                         $strFieldSet = sprintf(' <fieldset><legend>%s</legend><div class="notes"><h4>%s</h4><p class="last">%s</p></div>%s</fieldset>',
00450                                                         $field['legend'], $field['noteHeading'], $field['note'], $strFieldsetFields);
00451                         $strFormFields = $strFormFields . $strFieldSet;
00452                     break;
00453                     case "hidden":
00454                         if (!isset($field['value'])) {
00455                             $field['value'] = null;
00456                         }
00457                         $strFormFields = $strFormFields . $this->Html->hidden($field['tagName'], $field['value']);
00458                     break;
00459                     case "date":
00460                         if (!isset($field['selected'])) {
00461                             $field['selected'] = null;
00462                         }
00463                         $strFormFields = $strFormFields . $this->generateDate($field['tagName'], $field['prompt'], $field['required'], $field['errorMsg'], null, $field['htmlOptions'], $field['selected']);
00464                     break;
00465                     case "datetime":
00466                         if (!isset($field['selected'])) {
00467                             $field['selected'] = null;
00468                         }
00469                         $strFormFields = $strFormFields . $this->generateDateTime($field['tagName'], $field['prompt'], $field['required'], $field['errorMsg'], null, $field['htmlOptions'], $field['selected']);
00470                     break;
00471                     case "time":
00472                         if (!isset($field['selected'])) {
00473                             $field['selected'] = null;
00474                         }
00475                         $strFormFields = $strFormFields . $this->generateTime($field['tagName'], $field['prompt'], $field['required'], $field['errorMsg'], null, $field['htmlOptions'], $field['selected']);
00476                     break;
00477                     case "year":
00478                         if (!isset($field['selected'])) {
00479                             $field['selected'] = null;
00480                         }
00481                         $strFormFields = $strFormFields . $this->generateYear($field['tagName'], $field['prompt'], $field['required'], $field['errorMsg'], null, $field['htmlOptions'], $field['selected']);
00482                     break;
00483                     default:
00484                     break;
00485                 }
00486             }
00487         }
00488         return $strFormFields;
00489     }
00490 }
00491 ?>