CWIS Developer Documentation
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 
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  $StatesList = StdLib::GetUsStatesList();
441  array_unshift($StatesList, "--");
442 
443  return $StatesList;
444  }
445 
446 
447  # ---- PRIVATE INTERFACE -------------------------------------------------
448 
449  private $Fields;
450  private $ErrorColor;
451  private $AdditionalErrorCodes;
452  private $AdditionalErrorFields;
453  private $AdditionalErrorMessages;
454 
461  private function CheckFieldValue($FieldName)
462  {
463  $Value = isset($_POST[$FieldName]) ? $_POST[$FieldName]
464  : (isset($_GET[$FieldName]) ? $_GET[$FieldName] : NULL);
465  $ErrorCode = $this->Fields[$FieldName]->IsInvalidValue($Value);
466  return $ErrorCode;
467  }
468 }
IncomingFieldValuesHaveErrors()
Check the incoming form values for each field and report whether errors were found.
Definition: FormTool.php:174
PrintLabelForField($FieldName)
Print the label element for the given field.
Definition: FormTool.php:405
ErrorCodesAvailable()
Determine if there are any error codes available from the form.
Definition: FormTool.php:427
SetAdditionalErrorCodes($Codes)
Save additional error codes if not already present.
Definition: FormTool.php:274
Helps print and validate form fields, and their errors, associated with a form.
Definition: FormTool.php:14
static GetArrayOfUsStates()
Get an array of US state names with their two-letter abbreviations as the index.
Definition: FormTool.php:438
PrintField($FieldName)
Print the label and input for given form field.
Definition: FormTool.php:394
__construct($FormFields, $AdditionalErrorMessages=NULL)
Object constructor.
Definition: FormTool.php:25
GetErrorMessages($EliminateDuplicateMessages=TRUE)
Get the list of error messages based on the error codes from the URL via $_GET.
Definition: FormTool.php:318
GetValsAsUrlParams($IncludePasswords=FALSE)
Return the URL parameter string with form field values that are set in the POST variables.
Definition: FormTool.php:128
PrintInputForField($FieldName)
Print the input element for the given field.
Definition: FormTool.php:416
ValueForField($FieldName, $NewValue=NULL)
Get and set the value for a form field.
Definition: FormTool.php:89
GetErrorCodesAsUrlParams()
Return the URL parameter string with error codes for any form value errors.
Definition: FormTool.php:187
AllRequiredVarsAreSet()
Determine whether all of the required form field values are set in the POST variables.
Definition: FormTool.php:100
SetAdditionalErrorFields($FieldNames)
Save additional fields marked as having errors.
Definition: FormTool.php:252
static GetUsStatesList()
Get an array of US state names with their two-letter abbreviations as the index.
Definition: StdLib.php:749
GetUrlWithValuesAndErrorCodes($BaseUrl, $IncludePasswords=FALSE)
Convenience method that adds value and error codes to the URL.
Definition: FormTool.php:300
SetFieldValuesFromUrlParams()
Set the values for the form fields from the URL parameters when available.
Definition: FormTool.php:155