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 2011 Edward Almasy and Internet Scout Project
7 # http://scout.wisc.edu/
8 #
9 
10 class FormTool {
11 
12  # ---- PUBLIC INTERFACE --------------------------------------------------
13 
14  # object constructor
15  function FormTool($FormFields, $AdditionalErrorMessages = NULL)
16  {
17  # if form field value is not an array
18  if (!is_array($FormFields))
19  {
20  # look for form field file to include
21  $PossibleFileNames = array(
22  "local/include/%NAME%",
23  "local/include/%NAME%.php",
24  "local/include/Form--%NAME%.php",
25  "local/include/SPT--Form--%NAME%.php",
26  "include/%NAME%",
27  "include/%NAME%.php",
28  "include/Form--%NAME%.php",
29  "include/SPT--Form--%NAME%.php",
30  );
31  foreach ($PossibleFileNames as $FileName)
32  {
33  $FileName = str_replace("%NAME%", $FormFields, $FileName);
34  if (file_exists($FileName))
35  {
36  $FormFieldFile = $FileName;
37  break;
38  }
39  }
40 
41  # if form field file was found
42  if (isset($FormFieldFile))
43  {
44  # load form field file (should set $FormFields)
45  include_once($FormFieldFile);
46  }
47  }
48 
49  # save field info with field name as index
50  foreach ($FormFields as $Field)
51  {
52  $this->Fields[$Field->Name()] = $Field;
53  }
54 
55  # save additional error messages (if any)
56  $this->AdditionalErrorMessages = $AdditionalErrorMessages;
57 
58  # set default error color
59  $this->ErrorColor = "red";
60 
61  # save any additional fields indicated to be marked for error
62  if (isset($_GET["FTAddErrFields"]) && count($_GET["FTAddErrFields"]))
63  {
64  $this->AdditionalErrorFields = explode("!", $_GET["FTAddErrFields"]);
65  }
66  else
67  {
68  $this->AdditionalErrorFields = array();
69  }
70  }
71 
72  # get/set field values
73  function ValueForField($FieldName, $NewValue = NULL)
74  {
75  return $this->Fields[$FieldName]->Value($NewValue);
76  }
77 
78  # checks whether all required form variables are set in $_POST
80  {
81  # assume that all required variables will be found
82  $AllFound = TRUE;
83 
84  # for each required form variable
85  foreach ($this->Fields as $FieldName => $Field)
86  {
87  # if variable is not set in $_POST
88  if (!isset($_POST[$FieldName]) || !strlen($_POST[$FieldName]))
89  {
90  # set flag indicating we found a missing var and exit loop
91  $AllFound = FALSE;
92  break;
93  }
94  }
95 
96  # report back to caller whether we found on required vars
97  return $AllFound;
98  }
99 
100  # return URL parameter string with form values that are set (from $_POST)
101  # (returns empty string if none of the form values are set)
102  # (URL parameter string does not include leading separator (? or &))
103  function GetValsAsUrlParams($IncludePasswords = FALSE)
104  {
105  # assume no values will be found
106  $UrlParams = "";
107 
108  # for each form field
109  foreach ($this->Fields as $FieldName => $Field)
110  {
111  # if form value is set and contains something and is not excluded
112  if (isset($_POST[$FieldName])
113  && strlen(trim($_POST[$FieldName]))
114  && (!$Field->IsPassword() || $IncludePasswords))
115  {
116  # add value to URL param string
117  $UrlParams = strlen($UrlParams)
118  ? $UrlParams."&".$FieldName."=".urlencode($_POST[$FieldName])
119  : $FieldName."=".urlencode($_POST[$FieldName]);
120  }
121  }
122 
123  # return parameter string to caller
124  return $UrlParams;
125  }
126 
127  # set field values from URL parameters where available
129  {
130  # for each field
131  foreach ($this->Fields as $FieldName => $Field)
132  {
133  # if value is available for field in incoming GET parameters
134  if (isset($_GET[$FieldName]))
135  {
136  # set field value
137  $Field->Value($_GET[$FieldName]);
138  }
139  }
140  }
141 
142  # check form values for each field and report whether errors found
144  {
145  return (count($_GET) || count($_POST)) ?
146  (strlen($this->GetErrorCodesAsUrlParams()) ? TRUE : FALSE) : FALSE;
147  }
148 
149  # return URL parameter string with codes for any form value errors
150  # (returns empty string if no errors found)
151  # (URL parameter string does not include leading separator (? or &))
153  {
154  # start with empty error code string
155  $ErrorCodeString = "";
156 
157  # for each field value
158  foreach ($this->Fields as $FieldName => $Field)
159  {
160  # if validation function says that value is invalid
161  $ErrorCode = $this->CheckFieldValue($FieldName);
162  if ($ErrorCode)
163  {
164  # add error code for value to error code string
165  $ErrorCodeString .= (strlen($ErrorCodeString) ? "!" : "")
166  .$FieldName."-".$ErrorCode;
167  }
168  }
169 
170  # if values were added to error code string
171  if (strlen($ErrorCodeString))
172  {
173  # prepend name of GET variable to contain error codes
174  $ErrorCodeString = "FTFieldErrs=".$ErrorCodeString;
175  }
176 
177  # if additional error codes were supplied
178  if (isset($this->AdditionalErrorCodes) && count($this->AdditionalErrorCodes))
179  {
180  # for each additional error code
181  foreach ($this->AdditionalErrorCodes as $Code)
182  {
183  # append code to string
184  $AddCodeString = isset($AddCodeString) ? $AddCodeString."!".$Code
185  : $Code;
186  }
187 
188  # append additional error code string to error code string
189  $ErrorCodeString .= (strlen($ErrorCodeString) ? "&" : "")
190  ."FTAddErrCodes=".$AddCodeString;
191  }
192 
193  # if additional fields were supplied to be marked as erroneous
194  if (count($this->AdditionalErrorFields))
195  {
196  # for each additional error code
197  foreach ($this->AdditionalErrorFields as $FieldName)
198  {
199  # append code to string
200  $AddFieldString = isset($AddFieldString) ? $AddFieldString."!".$FieldName
201  : $FieldName;
202  }
203 
204  # append additional error code string to error code string
205  $ErrorCodeString .= (strlen($ErrorCodeString) ? "&" : "")
206  ."FTAddErrFields=".$AddFieldString;
207  }
208 
209  # return error code string to caller
210  return $ErrorCodeString;
211  }
212 
213  # save additional fields to be marked as having errors
214  function SetAdditionalErrorFields($FieldNames)
215  {
216  # convert to array if needed
217  if (!is_array($FieldNames))
218  {
219  $FieldNames = array($FieldNames);
220  }
221 
222  # save fields (if not already present)
223  foreach ($FieldNames as $FieldName)
224  {
225  if (!in_array($FieldName, $this->AdditionalErrorFields))
226  {
227  $this->AdditionalErrorFields[] = $FieldName;
228  }
229  }
230  }
231 
232  # save additional error codes
233  function SetAdditionalErrorCodes($Codes)
234  {
235  # convert to array if needed
236  if (!is_array($Codes))
237  {
238  $Codes = array($Codes);
239  }
240 
241  # save codes (if not already present)
242  foreach ($Codes as $Code)
243  {
244  if (!isset($this->AdditionalErrorCodes)
245  || !in_array($Code, $this->AdditionalErrorCodes))
246  {
247  $this->AdditionalErrorCodes[] = $Code;
248  }
249  }
250  }
251 
252  # convenience function that adds value and err codes to URL
253  function GetUrlWithValuesAndErrorCodes($BaseUrl, $IncludePasswords = FALSE)
254  {
255  $ValParams = $this->GetValsAsUrlParams($IncludePasswords);
256  $ErrParams = $this->GetErrorCodesAsUrlParams();
257  $ParamStart = strpos($BaseUrl, "?") ? "&" : "?";
258  return $BaseUrl
259  .(strlen($ValParams) ? $ParamStart.$ValParams : "")
260  .(strlen($ErrParams) ?
261  (strlen($ValParams) ? "&" : $ParamStart).$ErrParams : "");
262  }
263 
264  # get list of error messages based on codes from URL ($_GET)
265  function GetErrorMessages($EliminateDuplicateMessages = TRUE)
266  {
267  # start with empty list
268  $ErrorList = array();
269 
270  # if it looks like there are field-specific error messages to be had
271  if (isset($_GET["FTFieldErrs"]))
272  {
273  # split error data into list of fields
274  $FieldList = explode("!", $_GET["FTFieldErrs"]);
275 
276  # for each field found
277  foreach ($FieldList as $FieldListEntry)
278  {
279  # split field entry into name and code
280  list($FieldName, $ErrorCode) = explode("-", $FieldListEntry);
281 
282  # if we know about this field
283  if (isset($this->Fields[$FieldName]))
284  {
285  # translate error code into message and add to list
286  $Field = $this->Fields[$FieldName];
287  $Replacements = array(
288  "%N" => "<i>".$Field->Name()."</i>",
289  "%V" => "<i>".$Field->Value()."</i>",
290  "%L" => "<i>".preg_replace("/:$/", "", $Field->Label())."</i>",
291  "%C" => "<i>".$ErrorCode."</i>",
292  );
293  $Message = $Field->GetInvalidValueMessage($ErrorCode);
294  $ErrorList[$FieldName] = str_replace(
295  array_keys($Replacements), $Replacements, $Message);
296  }
297  }
298  }
299 
300  # if it looks like there are additional general error messages to be had
301  if (isset($_GET["FTAddErrCodes"]) && count($this->AdditionalErrorMessages))
302  {
303  # split error data into list of codes
304  $CodeList = explode("!", $_GET["FTAddErrCodes"]);
305 
306  # for each code found
307  foreach ($CodeList as $Code)
308  {
309  # if there is a message corresponding to this code
310  if (isset($this->AdditionalErrorMessages[$Code]))
311  {
312  # add message to list
313  $ErrorList[$Code] = $this->AdditionalErrorMessages[$Code];
314  }
315  }
316  }
317 
318  # remove duplicate messages (if requested by caller)
319  if ($EliminateDuplicateMessages)
320  {
321  $NewErrorList = array();
322  foreach ($ErrorList as $Code => $Message)
323  {
324  if (!in_array($Message, $NewErrorList))
325  {
326  $NewErrorList[$Code] = $Message;
327  }
328  }
329  $ErrorList = $NewErrorList;
330  }
331 
332  # return list of error messages to caller
333  return $ErrorList;
334  }
335 
336  # print tags for specified field
337  function PrintField($FieldName)
338  {
339  $this->Fields[$FieldName]->PrintField(
340  ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName))
341  || in_array($FieldName, $this->AdditionalErrorFields));
342  }
343  function PrintLabelForField($FieldName)
344  {
345  $this->Fields[$FieldName]->PrintLabel(
346  ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName))
347  || in_array($FieldName, $this->AdditionalErrorFields));
348  }
349  function PrintInputForField($FieldName)
350  {
351  $this->Fields[$FieldName]->PrintInput(
352  ($this->ErrorCodesAvailable() && $this->CheckFieldValue($FieldName))
353  || in_array($FieldName, $this->AdditionalErrorFields));
354  }
355 
356  # report whether error codes are available
358  {
359  return isset($_GET["FTFieldErrs"]) || isset($_GET["FTAddErrCodes"]);
360  }
361 
362  # return array of US state names with two-letter abbreviations as index
363  static function GetArrayOfUsStates()
364  {
365  return array(
366  "" => "--",
367  "AL" => "Alabama",
368  "AK" => "Alaska",
369  "AZ" => "Arizona",
370  "AR" => "Arkansas",
371  "CA" => "California",
372  "CO" => "Colorado",
373  "CT" => "Connecticut",
374  "DE" => "Delaware",
375  "DC" => "District of Columbia",
376  "FL" => "Florida",
377  "GA" => "Georgia",
378  "HI" => "Hawaii",
379  "ID" => "Idaho",
380  "IL" => "Illinois",
381  "IN" => "Indiana",
382  "IA" => "Iowa",
383  "KS" => "Kansas",
384  "KY" => "Kentucky",
385  "LA" => "Louisiana",
386  "ME" => "Maine",
387  "MD" => "Maryland",
388  "MA" => "Massachusetts",
389  "MI" => "Michigan",
390  "MN" => "Minnesota",
391  "MS" => "Mississippi",
392  "MO" => "Missouri",
393  "MT" => "Montana",
394  "NE" => "Nebraska",
395  "NV" => "Nevada",
396  "NH" => "New Hampshire",
397  "NJ" => "New Jersey",
398  "NM" => "New Mexico",
399  "NY" => "New York",
400  "NC" => "North Carolina",
401  "ND" => "North Dakota",
402  "OH" => "Ohio",
403  "OK" => "Oklahoma",
404  "OR" => "Oregon",
405  "PA" => "Pennsylvania",
406  "RI" => "Rhode Island",
407  "SC" => "South Carolina",
408  "SD" => "South Dakota",
409  "TN" => "Tennessee",
410  "TX" => "Texas",
411  "UT" => "Utah",
412  "VT" => "Vermont",
413  "VA" => "Virginia",
414  "WA" => "Washington",
415  "WV" => "West Virginia",
416  "WI" => "Wisconsin",
417  "WY" => "Wyoming",
418  );
419  }
420 
421 
422  # ---- PRIVATE INTERFACE -------------------------------------------------
423 
424  var $Fields;
429 
430  # check form (POST) value for specified field and return error code
431  function CheckFieldValue($FieldName)
432  {
433  $Value = isset($_POST[$FieldName]) ? $_POST[$FieldName]
434  : (isset($_GET[$FieldName]) ? $_GET[$FieldName] : NULL);
435  $ErrorCode = $this->Fields[$FieldName]->IsInvalidValue($Value);
436  return $ErrorCode;
437  }
438 }