Search:

# CWIS Developers Documentation

- Main Page
- Classes
- Files

- Search for |

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