Class: MailForm

[line 274]
MailForm provides methods for generating, validating, and handling web

forms. Forms can be handled automatically (sent to an email address), or handled using "action files". Action files are passed to the handle () method, and can be used to do anything you want to the form values. MailForm will generate forms for you, using a basic HTML tabled layout, which is okay for most applications, or you can have complete visual customization through form templates. MailForm also exposes an EasyText tag, which makes it much quicker to create fully validating forms in minutes.

New in 2.0:

• 16 widgets, including date and time widgets, a directory listing widget, and more.
• 11 different validation rules, including a regular expression rule, cross form widget comparisons (good for password verification widgets), and calling to pre-defined functions.
• Many speed improvements, such as dynamic loading of widgets, so your form only loads the necessary widgets.
• MailForm 2.0 is a complete rewrite, which has a much cleaner API, although it is not backward compatible with 1.0, other than through its EasyText tag.

Widget Types:

• checkbox
• date
• datetime
• dirlist
• file
• hidden
• image
• multiple (multi-line select box)
• password
• radio
• reset
• select
• submit
• text
• textarea
• time

Validation Rules:

• is "value"
• contains "some value"
• regex "some regex"
• equals "anotherfield"
• not empty
• length "6+" (eg: 6, 6+, 6-12, 12-)
• gt "value"
• ge "value"
• lt "value"
• le "value"
• func "func_name" (or function "func_name")

Miscellaneous:

• Do not use underscores (_) in the naming of complex widgets (ie. the datetime widget).

New in 2.2:

• Added an 'Extra' parameter to the EasyText =MailForm tag parameter list, so that the File widget can be used without having to resort to coding the form in PHP instead.
• Fixed a bug in the EasyText() method, where the value of the Email property wasn't being passed on.

New in 2.4:

• Changed a reference to "$GLOBALS['PHP_SELF']" to "global $_SERVER; $_SERVER['PHP_SELF']" so that it works with register_globals off.
• Added File widgets to the list of widgets skipped on the isset() condition in invalid(), because some browsers don't send file fields at all if there is no file. This may inhibit file field validation, but it's necessary due to inconsistencies across browsers.

New in 2.6:

• Moved the validation layer into the Widget level. See saf.MailForm.Widget and saf.MailForm.Rule for more info.
• Added a template example to the DocReader docs below.

New in 2.8:

• Fixed a bug in getValues() that caused the $vars passed to a validation function to be blank.
• Fixed EasyText() to use the new addRule() method instead of validation(), and added the ability to include multiple rules for the same widget through EasyText() using commas as separators.
• Added a $submitted property which is used by setValues() to keep an accurate reading on widgets whose $passover_isset property is set to true.

New in 3.0:

• Added an $_attrs property and three new methods, attr(), unsetAttr(), and getAttrs().
• Deprecated the $extra property in favour of the new property and methods just added.
• Improved the email output formatting in handle().

New in 3.2:

• Deprecated the handle() method in favour of a setHandler(), run(), and onSubmit() methods. These methods make it easier to subclass MailForm to unify the location of the form definition and handling.
• Added $sendTo, $sendFrom, $sendExtra, $screenReply, and $handler support properties to the new methods.
• Added a parseSettings() method, which makes it much easier to create new forms.
• getValues() and invalid() now do not use a passed $cgi object, and instead both rely on a global $cgi object, which is set automatically in the Sitellite Content Server, Content Manager, and the init.php script in SAF itself, so it's reasonable to assume it will be available. This doesn't affect code that still passes the object to invalid(), and the parameter was deprecated in getValues() already anyway.
• getValues() now uses a new property called $uploadFiles, which tells it to upload files from file widgets for you automatically. This breaks backward compatibility as a default, but you can pass a false value to achieve the old behaviour.

New in 3.4:

• Added makeAssoc() and rememberFields() methods, for use with the Sitellite Content Server form API.
• Added a $title property, which will show in a top-level header above the form if provided.
• Added a global formdata_get() function which returns a key/value list from the global $formdata array defined in the application property files.
• Added a $uploadFile parameter to run(), which allows finer control over file upload handling.

New in 3.6:

• Removed the EasyText() and EasyTextInit() methods.
• Removed the saf.MailForm.Wizard package, since SCS now provides a more flexible, elegant, and clean, and less buggy way of accomplishing the same effect.
• Removed the EasyText widget.
• Added the ability to report all invalid rules at once, instead of just one. However, just one is still the default.

New in 3.8:

• Added the ability to call addWidget() by specifying the type as a loader path to an alternate location. This does not affect backward compatibility in any way.
• Added the ability to call addWidget () by passing a widget object as the $type parameter.

New in 4.0:

• FormHelp ins now integrated into MailForm. In settings.php, you can specify 'formhelp = yes' under [Form] and 'formhelp = Message' under any widget and the display of it is automatic.

1     <?php
2     
3      <?php
4     
5      $form = new MailForm;
6      $form->template = 'mf2template.spt';
7      $form->message = 'Please take a moment to fill out our form.';
8     
9      // old way to set attributes
10     //$form->extra = 'enctype="multipart/form-data"';
11    
12     // new way to set attributes
13     $form->attr ('enctype', 'multipart/form-data');
14    
15     // build the form
16    
17     // standard usage:
18     $form->addWidget ('text', 'username');
19     $form->widgets['username']->display_value = 'Username (min. 6 chars)';
20     $form->widgets['username']->addRule ('length "6-24"', 'Your username must be between 6 and 24 characters in length.  Please fix this to continue.');
21    
22     // or if you prefer:
23     $password =& $form->addWidget ('password', 'password');
24     $password->addRule ('length "6-24"', 'Your password must be between 6 and 24 characters in length.  Please fix this to continue.');
25    
26     $verify =& $form->addWidget ('password', 'verify');
27     $verify->display_value = 'Verify Password';
28     $verify->addRule ('equals "password"', 'Your passwords did not match.  Please fix this to continue.');
29    
30     $form->addWidget ('text', 'firstname');
31     $form->widgets['firstname']->validation ('not empty');
32     $form->addWidget ('text', 'lastname');
33     $form->widgets['lastname']->validation ('not empty');
34    
35     $province =& $form->addWidget ('select', 'province');
36     $province->setValues (array (
37         'BC' => 'British Columbia',
38         'MB' => 'Manitoba',
39         'ON' => 'Ontario',
40     ));
41     $province->default_value = 'MB';
42    
43     // the new 'dirlist' widget type
44     $dlist =& $form->addWidget ('dirlist', 'dltest');
45     $dlist->directory = 'pix';
46     $dlist->extensions = array ('jpg', 'gif', 'png');
47    
48     // the new 'date' widget type
49     $form->addWidget ('date', 'birth-date');
50     $form->widgets['birth-date']->display_value = 'Birth Date';
51    
52     $textarea =& $form->addWidget ('textarea', 'comments');
53     $textarea->setValue ('hello world!');
54     $textarea->addRule ('not empty', 'You must enter a comment.  Please fix this to continue.');
55    
56     $send =& $form->addWidget ('submit', 'send');
57     $send->setValues ('Submit!');
58    
59     if ($form->invalid ($cgi)) {
60    
61         // form is invalid or has not been set yet
62         $form->setValues ($cgi, $invalid_field);
63         echo $form->show ('inc/html/formtemplate.spt');
64    
65     } else {
66    
67         // handle submitted form
68    
69         if (! $form->handle ('lux@simian.ca', 'Mail Form')) {
70             echo 'Error: ' . $form->error_message;
71         }
72    
73     }
74    
75     ? >
76    
77     -----
78     inc/html/formtemplate.spt (Note: Replace ** with { and }):
79    
80     <form method="**mailform_method**" action="**mailform_action**" **mailform_extra**>
81     <p>**mailform_message**</p>
82    
83     <p>Username<br />**username**</p>
84     <p>Password<br />**password**</p>
85     <p>Verify Password<br />**verify**</p>
86     <p>First Name<br />**firstname**</p>
87     <p>Last Name<br />**lastname**</p>
88     <p>Province<br />**province**</p>
89     <p>Pick an image<br />**dltest**</p>
90     <p>Birthday<br />**birth-date**</p>
91     <p>Comments<br />**comments**</p>
92     <p>**send**</p>
93    
94     </form>
95    
96    
97     ? >

Tags:

$action =

[line 300]

The value of the action attribute of the HTML form tag.

$action is actually an alias for $_attrs['action'].

Tags:

$blacklist =  true

[line 495]

Whether to verify the remote address of the form submitter against a list of invalid IP addresses in the database table sitellite_form_blacklist so as to prevent repeated abuse from a single source.

Tags:

$clean_input =  false

[line 484]

Whether to strip all HTML and PHP tags/code from all input parameters.

This is off by default because it would break forms with the Xed editor by default, so it must be enabled as needed. Note that this can be enabled in a form's settings file under the [Form] block via: clean_input = yes

Tags:

$error_message =

[line 352]

Contains the message from any internal errors.

Tags:

$error_mode =  'single'

[line 365]

Determines the way in which error messages are displayed.

The default ('single') is to display the error message for the first invalid field only. The other ('all') is to display a list of all invalid fields with their corresponding error messages. Please note that $error_mode 'all' assumes that a custom error message is provided for every rule.

Tags:

$extra =

[line 344]

A way to pass extra parameters to the HTML form tag, for example 'enctype="multipart/formdata"'. Notice: This property is deprecated in favour of the $_attrs list and the attr() and unset() methods.

Tags:

$handler =

[line 452]

The function or object method to use to handle the submitted form.

This function or method will be called by the run() method. Use the setHandler() method to change this setting.

Tags:

$invalid = array ()

[line 374]

A list of all invalid fields in the form, and their corresponding error messages.

Tags:

$invalid_field =  ''

[line 282]

Contains the name of the widget that did not validate during the last call to the invalid () method.

Tags:

$message =

[line 333]

The initial message to be displayed at the top of the form.

Tags:

$method =

[line 291]

The value of the method attribute of the HTML form tag.

$method is actually an alias for $_attrs['method'].

Tags:

$name =

[line 393]

The name of this form. Optional. $name is actually an alias for $_attrs['name'].

Tags:

$screenReply =  'Thank you.  Your form has been sent.'

[line 442]

The response to return upon a successfully submitted form in the default handler. Defaults to "Thank you. Your form has been sent."

Tags:

$sendExtra =  ''

[line 425]

Any extra parameters for the mail() function in the default handler.

Tags:

$sendFrom =  ''

[line 417]

The email address to send the form from in the default handler.

Tags:

$sendSubject =  'Mail Form'

[line 433]

The subject line of the email to send from the default handler.

Tags:

$sendTo =

[line 409]

The email address to send the form to in the default handler.

Tags:

$template =

[line 317]

The optional template file or data used to customize the look of the form.

Tags:

$title =

[line 325]

The title to be displayed at the top of the form.

Tags:

$uploadFiles =  true

[line 461]

Whether to upload files automatically or to leave them for a custom saving mechanism.

Tags:

$verify_sender =  false

[line 472]

Whether to verify the REQUEST_METHOD and HTTP_REFERER headers to make

it more difficult (although not impossible) for spammers to abuse your form. Note that this can be enabled in a form's settings file under the [Form] block via: verify_sender = yes

Tags:

$verify_session =  true

[line 511]

Whether to verify that the submitter can accept session data, which

helps ensure they are a legitimate human user. Passing session verification requires cookies to be enabled for the submitter, which may help prevent abuse in combination with the other abuse-prevention techniques because a spambot may ignore the cookie, however this restricts forms for legitimate visitors who have cookies disabled in their browser (only a very small number of users disable cookies, but some do). To disable for a single form, add verify_session = no to its settings.php form.

Tags:

$widgets = array ()

[line 308]

An array of form widgets.

Tags:

---

constructor MailForm [line 523]

---

method addWidget [line 579]

---

method attr [line 1328]

---

method createWidget [line 1160]

---

method formatEmail [line 1080]

---

method getAttrs [line 1363]

---

method getValues [line 875]

---

method handle [line 1038]

---

method invalid [line 608]

---

method makeAssoc [line 1283]

---

method onSubmit [line 976]

---

method parseSettings [line 1115]

---

method rememberFields [line 1305]

---

method run [line 928]

---

method setHandler [line 910]

---

method setValues [line 699]

---

method show [line 736]

---

method unsetAttr [line 1349]

---

method verifyReferer [line 1384]

---

method verifyRequestMethod [line 1377]