Search:

CWIS Developers Documentation

  • Main Page
  • Classes
  • Files
  • File List
  • File Members

FormTool.php

Go to the documentation of this file.
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 ?>
CWIS logo doxygen
Copyright 2009 Internet Scout