CWIS Developer Documentation

- Home
- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

FormTool.php
Go to the documentation of this file.
1 <?PHP
2 #
3 # FILE: FormTool.php
4 #
5 # Part of the Collection Workflow Integration System (CWIS)
6 # Copyright 2002-2015 Edward Almasy and Internet Scout Research Group
7 # http://scout.wisc.edu/cwis/
8 #
9
14 class FormTool
15 {
16 # ---- PUBLIC INTERFACE --------------------------------------------------
17
25 public function __construct($FormFields, $AdditionalErrorMessages = NULL)
26 {
27 # if form field value is not an array
28 if (!is_array($FormFields))
29 {
30 # look for form field file to include
31 $PossibleFileNames = array(
32 "local/include/%NAME%",
33 "local/include/%NAME%.php",
34 "local/include/Form--%NAME%.php",
35 "local/include/SPT--Form--%NAME%.php",
36 "include/%NAME%",
37 "include/%NAME%.php",
38 "include/Form--%NAME%.php",
39 "include/SPT--Form--%NAME%.php",
40 );
41 foreach ($PossibleFileNames as $FileName)
42 {
43 $FileName = str_replace("%NAME%", $FormFields, $FileName);
44 if (file_exists($FileName))
45 {
46 $FormFieldFile = $FileName;
47 break;
48 }
49 }
50
51 # if form field file was found
52 if (isset($FormFieldFile))
53 {
54 # load form field file (should set $FormFields)
55 include_once($FormFieldFile);
56 }
57 }
58
59 # save field info with field name as index
60 foreach ($FormFields as $Field)
61 {
62 $this->Fields[$Field->Name()] = $Field;
63 }
64
65 # save additional error messages (if any)
66 $this->AdditionalErrorMessages = $AdditionalErrorMessages;
67
68 # set default error color
69 $this->ErrorColor = "red";
70
71 # save any additional fields indicated to be marked for error
72 if (isset($_GET["FTAddErrFields"]) && count($_GET["FTAddErrFields"]))
73 {
74 $this->AdditionalErrorFields = explode("!", $_GET["FTAddErrFields"]);
75 }
76 else
77 {
78 $this->AdditionalErrorFields = array();
79 }
80 }
81
89 public function ValueForField($FieldName, $NewValue = NULL)
90 {
91 return $this->Fields[$FieldName]->Value($NewValue);
92 }
93
100 public function AllRequiredVarsAreSet()
101 {
102 # assume that all required variables will be found
103 $AllFound = TRUE;
104
105 # for each required form variable
106 foreach ($this->Fields as $FieldName => $Field)
107 {
108 # if variable is not set in $_POST
109 if (!isset($_POST[$FieldName]) || !strlen($_POST[$FieldName]))
110 {
111 # set flag indicating we found a missing var and exit loop
112 $AllFound = FALSE;
113 break;
114 }
115 }
116
117 # report back to caller whether we found on required vars
118 return $AllFound;
119 }
120
128 public function GetValsAsUrlParams($IncludePasswords = FALSE)
129 {
130 # assume no values will be found
131 $UrlParams = "";
132
133 # for each form field
134 foreach ($this->Fields as $FieldName => $Field)
135 {
136 # if form value is set and contains something and is not excluded
137 if (isset($_POST[$FieldName])
138 && strlen(trim($_POST[$FieldName]))
139 && (!$Field->IsPassword() || $IncludePasswords))
140 {
141 # add value to URL param string
142 $UrlParams = strlen($UrlParams)
143 ? $UrlParams."&".$FieldName."=".urlencode($_POST[$FieldName])
144 : $FieldName."=".urlencode($_POST[$FieldName]);
145 }
146 }
147
148 # return parameter string to caller
149 return $UrlParams;
150 }
151
155 public function SetFieldValuesFromUrlParams()
156 {
157 # for each field
158 foreach ($this->Fields as $FieldName => $Field)
159 {
160 # if value is available for field in incoming GET parameters
161 if (isset($_GET[$FieldName]))
162 {
163 # set field value
164 $Field->Value($_GET[$FieldName]);
165 }
166 }
167 }
168
174 public function IncomingFieldValuesHaveErrors()
175 {
176 return (count($_GET) || count($_POST)) ?
177 (strlen($this->GetErrorCodesAsUrlParams()) ? TRUE : FALSE) : FALSE;
178 }
179
187 public function GetErrorCodesAsUrlParams()
188 {
189 # start with empty error code string
190 $ErrorCodeString = "";
191
192 # for each field value
193 foreach ($this->Fields as $FieldName => $Field)
194 {
195 # if validation function says that value is invalid
196 $ErrorCode = $this->CheckFieldValue($FieldName);
197 if ($ErrorCode)
198 {
199 # add error code for value to error code string
200 $ErrorCodeString .= (strlen($ErrorCodeString) ? "!" : "")
201 .$FieldName."-".$ErrorCode;
202 }
203 }
204
205 # if values were added to error code string
206 if (strlen($ErrorCodeString))
207 {
208 # prepend name of GET variable to contain error codes
209 $ErrorCodeString = "FTFieldErrs=".$ErrorCodeString;
210 }
211
212 # if additional error codes were supplied
213 if (isset($this->AdditionalErrorCodes) && count($this->AdditionalErrorCodes))
214 {
215 # for each additional error code
216 foreach ($this->AdditionalErrorCodes as $Code)
217 {
218 # append code to string
219 $AddCodeString = isset($AddCodeString) ? $AddCodeString."!".$Code
220 : $Code;
221 }
222
223 # append additional error code string to error code string
224 $ErrorCodeString .= (strlen($ErrorCodeString) ? "&" : "")
225 ."FTAddErrCodes=".$AddCodeString;
226 }
227
228 # if additional fields were supplied to be marked as erroneous
229 if (count($this->AdditionalErrorFields))
230 {
231 # for each additional error code
232 foreach ($this->AdditionalErrorFields as $FieldName)
233 {
234 # append code to string
235 $AddFieldString = isset($AddFieldString) ? $AddFieldString."!".$FieldName
236 : $FieldName;
237 }
238
239 # append additional error code string to error code string
240 $ErrorCodeString .= (strlen($ErrorCodeString) ? "&" : "")
241 ."FTAddErrFields=".$AddFieldString;
242 }
243
244 # return error code string to caller
245 return $ErrorCodeString;
246 }
247
252 public function SetAdditionalErrorFields($FieldNames)
253 {
254 # convert to array if needed
255 if (!is_array($FieldNames))
256 {
257 $FieldNames = array($FieldNames);
258 }
259
260 # save fields (if not already present)
261 foreach ($FieldNames as $FieldName)
262 {
263 if (!in_array($FieldName, $this->AdditionalErrorFields))
264 {
265 $this->AdditionalErrorFields[] = $FieldName;
266 }
267 }
268 }
269
274 public function SetAdditionalErrorCodes($Codes)
275 {
276 # convert to array if needed
277 if (!is_array($Codes))
278 {
279 $Codes = array($Codes);
280 }
281
282 # save codes (if not already present)
283 foreach ($Codes as $Code)
284 {
285 if (!isset($this->AdditionalErrorCodes)
286 || !in_array($Code, $this->AdditionalErrorCodes))
287 {
288 $this->AdditionalErrorCodes[] = $Code;
289 }
290 }
291 }
292
300 public function GetUrlWithValuesAndErrorCodes($BaseUrl, $IncludePasswords = FALSE)
301 {
302 $ValParams = $this->GetValsAsUrlParams($IncludePasswords);
303 $ErrParams = $this->GetErrorCodesAsUrlParams();
304 $ParamStart = strpos($BaseUrl, "?") ? "&" : "?";
305 return $BaseUrl
306 .(strlen($ValParams) ? $ParamStart.$ValParams : "")
307 .(strlen($ErrParams) ?
308 (strlen($ValParams) ? "&" : $ParamStart).$ErrParams : "");
309 }
310
318 public function GetErrorMessages($EliminateDuplicateMessages = TRUE)
319 {
320 # start with empty list
321 $ErrorList = array();
322
323 # if it looks like there are field-specific error messages to be had
324 if (isset($_GET["FTFieldErrs"]))
325 {
326 # split error data into list of fields
327 $FieldList = explode("!", $_GET["FTFieldErrs"]);
328
329 # for each field found
330 foreach ($FieldList as $FieldListEntry)
331 {
332 # split field entry into name and code
333 list($FieldName, $ErrorCode) = explode("-", $FieldListEntry);
334
335 # if we know about this field
336 if (isset($this->Fields[$FieldName]))
337 {
338 # translate error code into message and add to list
339 $Field = $this->Fields[$FieldName];
340 $Replacements = array(
341 "%N" => "<i>".$Field->Name()."</i>",
342 "%V" => "<i>".$Field->Value()."</i>",
343 "%L" => "<i>".preg_replace("/:$/", "",
344 $Field->Label())."</i>",
345 "%C" => "<i>".$ErrorCode."</i>",
346 );
347 $Message = $Field->GetInvalidValueMessage($ErrorCode);
348 $ErrorList[$FieldName] = str_replace(
349 array_keys($Replacements), $Replacements, $Message);
350 }
351 }
352 }
353
354 # if it looks like there are additional general error messages to be had
355 if (isset($_GET["FTAddErrCodes"]) && count($this->AdditionalErrorMessages))
356 {
357 # split error data into list of codes
358 $CodeList = explode("!", $_GET["FTAddErrCodes"]);
359
360 # for each code found
361 foreach ($CodeList as $Code)
362 {
363 # if there is a message corresponding to this code
364 if (isset($this->AdditionalErrorMessages[$Code]))
365 {
366 # add message to list
367 $ErrorList[$Code] = $this->AdditionalErrorMessages[$Code];
368 }
369 }
370 }
371
372 # remove duplicate messages (if requested by caller)
373 if ($EliminateDuplicateMessages)
374 {
375 $NewErrorList = array();
376 foreach ($ErrorList as $Code => $Message)
377 {
378 if (!in_array($Message, $NewErrorList))
379 {
380 $NewErrorList[$Code] = $Message;
381 }
382 }
383 $ErrorList = $NewErrorList;
384 }
385
386 # return list of error messages to caller
387 return $ErrorList;
388 }
389
394 public function PrintField($FieldName)
395 {
396 $this->Fields[$FieldName]->PrintField(
397 ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName))
398 || in_array($FieldName, $this->AdditionalErrorFields));
399 }
400
405 public function PrintLabelForField($FieldName)
406 {
407 $this->Fields[$FieldName]->PrintLabel(
408 ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName))
409 || in_array($FieldName, $this->AdditionalErrorFields));
410 }
411
416 public function PrintInputForField($FieldName)
417 {
418 $this->Fields[$FieldName]->PrintInput(
419 ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName))
420 || in_array($FieldName, $this->AdditionalErrorFields));
421 }
422
427 public function ErrorCodesAvailable()
428 {
429 return isset($_GET["FTFieldErrs"]) || isset($_GET["FTAddErrCodes"]);
430 }
431
438 public static function GetArrayOfUsStates()
439 {
440 return array(
441 "" => "--",
442 "AL" => "Alabama",
443 "AK" => "Alaska",
444 "AZ" => "Arizona",
445 "AR" => "Arkansas",
446 "CA" => "California",
447 "CO" => "Colorado",
448 "CT" => "Connecticut",
449 "DE" => "Delaware",
450 "DC" => "District of Columbia",
451 "FL" => "Florida",
452 "GA" => "Georgia",
453 "HI" => "Hawaii",
454 "ID" => "Idaho",
455 "IL" => "Illinois",
456 "IN" => "Indiana",
457 "IA" => "Iowa",
458 "KS" => "Kansas",
459 "KY" => "Kentucky",
460 "LA" => "Louisiana",
461 "ME" => "Maine",
462 "MD" => "Maryland",
463 "MA" => "Massachusetts",
464 "MI" => "Michigan",
465 "MN" => "Minnesota",
466 "MS" => "Mississippi",
467 "MO" => "Missouri",
468 "MT" => "Montana",
469 "NE" => "Nebraska",
470 "NV" => "Nevada",
471 "NH" => "New Hampshire",
472 "NJ" => "New Jersey",
473 "NM" => "New Mexico",
474 "NY" => "New York",
475 "NC" => "North Carolina",
476 "ND" => "North Dakota",
477 "OH" => "Ohio",
478 "OK" => "Oklahoma",
479 "OR" => "Oregon",
480 "PA" => "Pennsylvania",
481 "RI" => "Rhode Island",
482 "SC" => "South Carolina",
483 "SD" => "South Dakota",
484 "TN" => "Tennessee",
485 "TX" => "Texas",
486 "UT" => "Utah",
487 "VT" => "Vermont",
488 "VA" => "Virginia",
489 "WA" => "Washington",
490 "WV" => "West Virginia",
491 "WI" => "Wisconsin",
492 "WY" => "Wyoming",
493 );
494 }
495
496
497 # ---- PRIVATE INTERFACE -------------------------------------------------
498
499 private $Fields;
500 private $ErrorColor;
501 private $AdditionalErrorCodes;
502 private $AdditionalErrorFields;
503 private $AdditionalErrorMessages;
504
511 private function CheckFieldValue($FieldName)
512 {
513 $Value = isset($_POST[$FieldName]) ? $_POST[$FieldName]
514 : (isset($_GET[$FieldName]) ? $_GET[$FieldName] : NULL);
515 $ErrorCode = $this->Fields[$FieldName]->IsInvalidValue($Value);
516 return $ErrorCode;
517 }
518 }
FormTool\IncomingFieldValuesHaveErrors
IncomingFieldValuesHaveErrors()
Check the incoming form values for each field and report whether errors were found.
Definition: FormTool.php:174
FormTool\PrintLabelForField
PrintLabelForField($FieldName)
Print the label element for the given field.
Definition: FormTool.php:405
FormTool\ErrorCodesAvailable
ErrorCodesAvailable()
Determine if there are any error codes available from the form.
Definition: FormTool.php:427
FormTool\SetAdditionalErrorCodes
SetAdditionalErrorCodes($Codes)
Save additional error codes if not already present.
Definition: FormTool.php:274
FormTool
Helps print and validate form fields, and their errors, associated with a form.
Definition: FormTool.php:14
FormTool\GetArrayOfUsStates
static GetArrayOfUsStates()
Get an array of US state names with their two-letter abbreviations as the index.
Definition: FormTool.php:438
FormTool\PrintField
PrintField($FieldName)
Print the label and input for given form field.
Definition: FormTool.php:394
FormTool\__construct
__construct($FormFields, $AdditionalErrorMessages=NULL)
Object constructor.
Definition: FormTool.php:25
FormTool\GetErrorMessages
GetErrorMessages($EliminateDuplicateMessages=TRUE)
Get the list of error messages based on the error codes from the URL via $_GET.
Definition: FormTool.php:318
FormTool\GetValsAsUrlParams
GetValsAsUrlParams($IncludePasswords=FALSE)
Return the URL parameter string with form field values that are set in the POST variables.
Definition: FormTool.php:128
FormTool\PrintInputForField
PrintInputForField($FieldName)
Print the input element for the given field.
Definition: FormTool.php:416
PHP
PHP
Definition: RSSClient--Test.php:12
FormTool\ValueForField
ValueForField($FieldName, $NewValue=NULL)
Get and set the value for a form field.
Definition: FormTool.php:89
FormTool\GetErrorCodesAsUrlParams
GetErrorCodesAsUrlParams()
Return the URL parameter string with error codes for any form value errors.
Definition: FormTool.php:187
FormTool\AllRequiredVarsAreSet
AllRequiredVarsAreSet()
Determine whether all of the required form field values are set in the POST variables.
Definition: FormTool.php:100
FormTool\SetAdditionalErrorFields
SetAdditionalErrorFields($FieldNames)
Save additional fields marked as having errors.
Definition: FormTool.php:252
FormTool\GetUrlWithValuesAndErrorCodes
GetUrlWithValuesAndErrorCodes($BaseUrl, $IncludePasswords=FALSE)
Convenience method that adds value and error codes to the URL.
Definition: FormTool.php:300
FormTool\SetFieldValuesFromUrlParams
SetFieldValuesFromUrlParams()
Set the values for the form fields from the URL parameters when available.
Definition: FormTool.php:155