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 ?>