00001 <?PHP 00002 00003 # 00004 # FILE: SPT--FormTool.php 00005 # 00006 # METHODS PROVIDED: 00007 # FormTool() 00008 # - constructor 00009 # SomeMethod($SomeParameter, $AnotherParameter) 00010 # - short description of method 00011 # 00012 # AUTHOR: Edward Almasy 00013 # 00014 # Part of the Scout Portal Toolkit 00015 # Copyright 2006 Internet Scout Project 00016 # http://scout.wisc.edu 00017 # 00018 00019 class FormTool { 00020 00021 # ---- PUBLIC INTERFACE -------------------------------------------------- 00022 00023 # object constructor 00024 function FormTool($FormFields, $AdditionalErrorMessages = NULL) 00025 { 00026 # save field info with field name as index 00027 foreach ($FormFields as $Field) 00028 { 00029 $this->Fields[$Field->Name()] = $Field; 00030 } 00031 00032 # save additional error messages (if any) 00033 $this->AdditionalErrorMessages = $AdditionalErrorMessages; 00034 00035 # set default error color 00036 $this->ErrorColor = "red"; 00037 00038 # save any additional fields indicated to be marked for error 00039 if (isset($_GET["FTAddErrFields"]) && count($_GET["FTAddErrFields"])) 00040 { 00041 $this->AdditionalErrorFields = explode("!", $_GET["FTAddErrFields"]); 00042 } 00043 else 00044 { 00045 $this->AdditionalErrorFields = array(); 00046 } 00047 } 00048 00049 # get/set field values 00050 function ValueForField($FieldName, $NewValue = NULL) 00051 { 00052 return $this->Fields[$FieldName]->Value($NewValue); 00053 } 00054 00055 # checks whether all required form variables are set in $_POST 00056 function AllRequiredVarsAreSet() 00057 { 00058 # assume that all required variables will be found 00059 $AllFound = TRUE; 00060 00061 # for each required form variable 00062 foreach ($this->Fields as $FieldName => $Field) 00063 { 00064 # if variable is not set in $_POST 00065 if (!isset($_POST[$FieldName]) || !strlen($_POST[$FieldName])) 00066 { 00067 # set flag indicating we found a missing var and exit loop 00068 $AllFound = FALSE; 00069 break; 00070 } 00071 } 00072 00073 # report back to caller whether we found on required vars 00074 return $AllFound; 00075 } 00076 00077 # return URL parameter string with form values that are set (from $_POST) 00078 # (returns empty string if none of the form values are set) 00079 # (URL parameter string does not include leading separator (? or &)) 00080 function GetValsAsUrlParams($IncludePasswords = FALSE) 00081 { 00082 # assume no values will be found 00083 $UrlParams = ""; 00084 00085 # for each form field 00086 foreach ($this->Fields as $FieldName => $Field) 00087 { 00088 # if form value is set and contains something and is not excluded 00089 if (isset($_POST[$FieldName]) 00090 && strlen(trim($_POST[$FieldName])) 00091 && (!$Field->IsPassword() || $IncludePasswords)) 00092 { 00093 # add value to URL param string 00094 $UrlParams = strlen($UrlParams) 00095 ? $UrlParams."&".$FieldName."=".urlencode($_POST[$FieldName]) 00096 : $FieldName."=".urlencode($_POST[$FieldName]); 00097 } 00098 } 00099 00100 # return parameter string to caller 00101 return $UrlParams; 00102 } 00103 00104 # set field values from URL parameters where available 00105 function SetFieldValuesFromUrlParams() 00106 { 00107 # for each field 00108 foreach ($this->Fields as $FieldName => $Field) 00109 { 00110 # if value is available for field in incoming GET parameters 00111 if (isset($_GET[$FieldName])) 00112 { 00113 # set field value 00114 $Field->Value($_GET[$FieldName]); 00115 } 00116 } 00117 } 00118 00119 # check form values for each field and report whether errors found 00120 function IncomingFieldValuesHaveErrors() 00121 { 00122 return (count($_GET) || count($_POST)) ? 00123 (strlen($this->GetErrorCodesAsUrlParams()) ? TRUE : FALSE) : FALSE; 00124 } 00125 00126 # return URL parameter string with codes for any form value errors 00127 # (returns empty string if no errors found) 00128 # (URL parameter string does not include leading separator (? or &)) 00129 function GetErrorCodesAsUrlParams() 00130 { 00131 # start with empty error code string 00132 $ErrorCodeString = ""; 00133 00134 # for each field value 00135 foreach ($this->Fields as $FieldName => $Field) 00136 { 00137 # if validation function says that value is invalid 00138 $ErrorCode = $this->CheckFieldValue($FieldName); 00139 if ($ErrorCode) 00140 { 00141 # add error code for value to error code string 00142 $ErrorCodeString .= (strlen($ErrorCodeString) ? "!" : "") 00143 .$FieldName."-".$ErrorCode; 00144 } 00145 } 00146 00147 # if values were added to error code string 00148 if (strlen($ErrorCodeString)) 00149 { 00150 # prepend name of GET variable to contain error codes 00151 $ErrorCodeString = "FTFieldErrs=".$ErrorCodeString; 00152 } 00153 00154 # if additional error codes were supplied 00155 if (isset($this->AdditionalErrorCodes) && count($this->AdditionalErrorCodes)) 00156 { 00157 # for each additional error code 00158 foreach ($this->AdditionalErrorCodes as $Code) 00159 { 00160 # append code to string 00161 $AddCodeString = isset($AddCodeString) ? $AddCodeString."!".$Code 00162 : $Code; 00163 } 00164 00165 # append additional error code string to error code string 00166 $ErrorCodeString .= (strlen($ErrorCodeString) ? "&" : "") 00167 ."FTAddErrCodes=".$AddCodeString; 00168 } 00169 00170 # if additional fields were supplied to be marked as erroneous 00171 if (count($this->AdditionalErrorFields)) 00172 { 00173 # for each additional error code 00174 foreach ($this->AdditionalErrorFields as $FieldName) 00175 { 00176 # append code to string 00177 $AddFieldString = isset($AddFieldString) ? $AddFieldString."!".$FieldName 00178 : $FieldName; 00179 } 00180 00181 # append additional error code string to error code string 00182 $ErrorCodeString .= (strlen($ErrorCodeString) ? "&" : "") 00183 ."FTAddErrFields=".$AddFieldString; 00184 } 00185 00186 # return error code string to caller 00187 return $ErrorCodeString; 00188 } 00189 00190 # save additional fields to be marked as having errors 00191 function SetAdditionalErrorFields($FieldNames) 00192 { 00193 # convert to array if needed 00194 if (!is_array($FieldNames)) 00195 { 00196 $FieldNames = array($FieldNames); 00197 } 00198 00199 # save fields (if not already present) 00200 foreach ($FieldNames as $FieldName) 00201 { 00202 if (!in_array($FieldName, $this->AdditionalErrorFields)) 00203 { 00204 $this->AdditionalErrorFields[] = $FieldName; 00205 } 00206 } 00207 } 00208 00209 # save additional error codes 00210 function SetAdditionalErrorCodes($Codes) 00211 { 00212 # convert to array if needed 00213 if (!is_array($Codes)) 00214 { 00215 $Codes = array($Codes); 00216 } 00217 00218 # save codes (if not already present) 00219 foreach ($Codes as $Code) 00220 { 00221 if (!isset($this->AdditionalErrorCodes) 00222 || !in_array($Code, $this->AdditionalErrorCodes)) 00223 { 00224 $this->AdditionalErrorCodes[] = $Code; 00225 } 00226 } 00227 } 00228 00229 # convenience function that adds value and err codes to URL 00230 function GetUrlWithValuesAndErrorCodes($BaseUrl, $IncludePasswords = FALSE) 00231 { 00232 $ValParams = $this->GetValsAsUrlParams($IncludePasswords); 00233 $ErrParams = $this->GetErrorCodesAsUrlParams(); 00234 $ParamStart = strpos($BaseUrl, "?") ? "&" : "?"; 00235 return $BaseUrl 00236 .(strlen($ValParams) ? $ParamStart.$ValParams : "") 00237 .(strlen($ErrParams) ? 00238 (strlen($ValParams) ? "&" : $ParamStart).$ErrParams : ""); 00239 } 00240 00241 # get list of error messages based on codes from URL ($_GET) 00242 function GetErrorMessages($EliminateDuplicateMessages = TRUE) 00243 { 00244 # start with empty list 00245 $ErrorList = array(); 00246 00247 # if it looks like there are field-specific error messages to be had 00248 if (isset($_GET["FTFieldErrs"])) 00249 { 00250 # split error data into list of fields 00251 $FieldList = explode("!", $_GET["FTFieldErrs"]); 00252 00253 # for each field found 00254 foreach ($FieldList as $FieldListEntry) 00255 { 00256 # split field entry into name and code 00257 list($FieldName, $ErrorCode) = explode("-", $FieldListEntry); 00258 00259 # if we know about this field 00260 if (isset($this->Fields[$FieldName])) 00261 { 00262 # translate error code into message and add to list 00263 $Field = $this->Fields[$FieldName]; 00264 $Replacements = array( 00265 "%N" => "<i>".$Field->Name()."</i>", 00266 "%V" => "<i>".$Field->Value()."</i>", 00267 "%L" => "<i>".preg_replace("/:$/", "", $Field->Label())."</i>", 00268 "%C" => "<i>".$ErrorCode."</i>", 00269 ); 00270 $Message = $Field->GetInvalidValueMessage($ErrorCode); 00271 $ErrorList[$FieldName] = str_replace( 00272 array_keys($Replacements), $Replacements, $Message); 00273 } 00274 } 00275 } 00276 00277 # if it looks like there are additional general error messages to be had 00278 if (isset($_GET["FTAddErrCodes"]) && count($this->AdditionalErrorMessages)) 00279 { 00280 # split error data into list of codes 00281 $CodeList = explode("!", $_GET["FTAddErrCodes"]); 00282 00283 # for each code found 00284 foreach ($CodeList as $Code) 00285 { 00286 # if there is a message corresponding to this code 00287 if (isset($this->AdditionalErrorMessages[$Code])) 00288 { 00289 # add message to list 00290 $ErrorList[$Code] = $this->AdditionalErrorMessages[$Code]; 00291 } 00292 } 00293 } 00294 00295 # remove duplicate messages (if requested by caller) 00296 if ($EliminateDuplicateMessages) 00297 { 00298 $NewErrorList = array(); 00299 foreach ($ErrorList as $Code => $Message) 00300 { 00301 if (!in_array($Message, $NewErrorList)) 00302 { 00303 $NewErrorList[$Code] = $Message; 00304 } 00305 } 00306 $ErrorList = $NewErrorList; 00307 } 00308 00309 # return list of error messages to caller 00310 return $ErrorList; 00311 } 00312 00313 # print tags for specified field 00314 function PrintField($FieldName) 00315 { 00316 $this->Fields[$FieldName]->PrintField( 00317 ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName)) 00318 || in_array($FieldName, $this->AdditionalErrorFields)); 00319 } 00320 function PrintLabelForField($FieldName) 00321 { 00322 $this->Fields[$FieldName]->PrintLabel( 00323 ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName)) 00324 || in_array($FieldName, $this->AdditionalErrorFields)); 00325 } 00326 function PrintInputForField($FieldName) 00327 { 00328 $this->Fields[$FieldName]->PrintInput( 00329 ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName)) 00330 || in_array($FieldName, $this->AdditionalErrorFields)); 00331 } 00332 00333 # report whether error codes are available 00334 function ErrorCodesAvailable() 00335 { 00336 return isset($_GET["FTFieldErrs"]) || isset($_GET["FTAddErrCodes"]); 00337 } 00338 00339 # return array of US state names with two-letter abbreviations as index 00340 # (may be called statically) 00341 function GetArrayOfUsStates() 00342 { 00343 return array( 00344 "" => "--", 00345 "AL" => "Alabama", 00346 "AK" => "Alaska", 00347 "AZ" => "Arizona", 00348 "AR" => "Arkansas", 00349 "CA" => "California", 00350 "CO" => "Colorado", 00351 "CT" => "Connecticut", 00352 "DE" => "Delaware", 00353 "DC" => "District of Columbia", 00354 "FL" => "Florida", 00355 "GA" => "Georgia", 00356 "HI" => "Hawaii", 00357 "ID" => "Idaho", 00358 "IL" => "Illinois", 00359 "IN" => "Indiana", 00360 "IA" => "Iowa", 00361 "KS" => "Kansas", 00362 "KY" => "Kentucky", 00363 "LA" => "Louisiana", 00364 "ME" => "Maine", 00365 "MD" => "Maryland", 00366 "MA" => "Massachusetts", 00367 "MI" => "Michigan", 00368 "MN" => "Minnesota", 00369 "MS" => "Mississippi", 00370 "MO" => "Missouri", 00371 "MT" => "Montana", 00372 "NE" => "Nebraska", 00373 "NV" => "Nevada", 00374 "NH" => "New Hampshire", 00375 "NJ" => "New Jersey", 00376 "NM" => "New Mexico", 00377 "NY" => "New York", 00378 "NC" => "North Carolina", 00379 "ND" => "North Dakota", 00380 "OH" => "Ohio", 00381 "OK" => "Oklahoma", 00382 "OR" => "Oregon", 00383 "PA" => "Pennsylvania", 00384 "RI" => "Rhode Island", 00385 "SC" => "South Carolina", 00386 "SD" => "South Dakota", 00387 "TN" => "Tennessee", 00388 "TX" => "Texas", 00389 "UT" => "Utah", 00390 "VT" => "Vermont", 00391 "VA" => "Virginia", 00392 "WA" => "Washington", 00393 "WV" => "West Virginia", 00394 "WI" => "Wisconsin", 00395 "WY" => "Wyoming", 00396 ); 00397 } 00398 00399 00400 # ---- PRIVATE INTERFACE ------------------------------------------------- 00401 00402 var $Fields; 00403 var $ErrorColor; 00404 var $AdditionalErrorCodes; 00405 var $AdditionalErrorFields; 00406 var $AdditionalErrorMessages; 00407 00408 # check form (POST) value for specified field and return error code 00409 function CheckFieldValue($FieldName) 00410 { 00411 $Value = isset($_POST[$FieldName]) ? $_POST[$FieldName] 00412 : (isset($_GET[$FieldName]) ? $_GET[$FieldName] : NULL); 00413 $ErrorCode = $this->Fields[$FieldName]->IsInvalidValue($Value); 00414 return $ErrorCode; 00415 } 00416 } 00417 00418 ?>