To begin with, take a look at the testform.php and test-form-details.php files included in the package. Those will give you a good start. The PHP code within the testform.php file will rarely need to be edited.
The code within test-form-details.php, however, will need to be edited heavily. The code in that file should be well-commented to get you started.
You should then view the source files themselves for more information about the available properties for each type of object.
Validation and Formatting:
To specify a valtype for a formfield, you should create an array with any/all of the following items:
'email'=>NULL, - This specifies that the value must be a valid e-mail address. This will also output an e-mail address (as an e-mail link) in the results. Also, if the nocopy property of the form/formset is not set to boolean true, a copy of the results will be sent to the address(es) specified in any field with this valtype set.
'phone'=>NULL, - This specifies that the value must be a valid phone number. This will also output a properly formatted phone number in the results. The number entered in the field must be either 7 or 10 digits (not including parens, hyphens or a leading 1). If it is not, it will throw an error. If the value is only 7 digits, the default area code (as set in the config file) will be prepended to the value.
'date'=>(bool) - false for a date, true for a date/time - This specifies that the value must be a valid date (as recognized by the PHP strtotime function). If it is not, an error will be thrown. This valtype will also return an AP style formatted date and/or date/time (if set to true).
'trimlen'=>(int) - length to which field value should be truncated
'zerofill'=>(int) - if the string length of the value is shorter than the integer specified with this valtype, it will be zero-filled from the left.
'maxlen'=>(int) - maximum length of string. If the value is longer than the max length, an error will be thrown.
'minlen'=>(int) - minimum length of string. If the value is shorter than the min length, an error will be thrown.
'exactlen'=>(int) - exact length field value should be. If the value is shorter or longer than the exact length, an error will be thrown.
'number'=>NULL - If the number valtype is specified, the value entered must be a valid number (according to the PHP is_numeric function). Otherwise, an error will be thrown.
'currency'=>NULL - If this valtype is specified, the value entered must be a valid number (according to the PHP is_numeric function). In addition, it will be returned in a currency format (currently only US currency format, with a US dollar symbol at the front, commas as thousands separator, a period as the decimal separator and two places after the decimal).
'cc=>NULL - If this valtype is specified, the value must be a valid credit card number. This valtype has not been tested yet, and should not be used on a production site without being properly tested. In addition, this valtype should probably not be used outside of the ccclass object, which is a collection of form fields (also not tested).
Notes about Checkboxes, Radio buttons, Select fields and Options:
1) Checkboxes and radio buttons are created using the checkgroup and radiogroup classes (respectively). They do not use standard labels the way other form fields do. Instead, the text you want displayed at the top of the groups of checkboxes or radio buttons should be specified using the title property.
2) Checkboxes within checkgroups, radio buttons within radiogroups and options within select elements are generated by setting the "options" property. The "options" property is an associative array with the "value" of the option/checkbox/radio button set as the "key" for the array and the text to be associated with the option/checkbox/radio button as the "value" of the array.
2a) To create a single optgroup to be used within a select element, you can insert a two-dimensional array within the options array that would look like: 'optgroup'=>array('options'=>array([value]=>[text],[value]=>[text]),'label'=>[label]). The key for this array item must be set to "optgroup". Because of that, only one optgroup can be created this way.
2b) To create multiple optgroups to use within a set of options, you will need to create an optgroup object for each optgroup. You will, unfortunately, also need to construct all of your other options (outside of the optgroups) by creating option objects for each. You will then add all of them to the myOpts property as an array, rather than adding them to the options array and having them constructed automatically through the constructor of the form field object.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Usage:
To begin with, take a look at the testform.php and test-form-details.php files included in the package. Those will give you a good start. The PHP code within the testform.php file will rarely need to be edited.
The code within test-form-details.php, however, will need to be edited heavily. The code in that file should be well-commented to get you started.
You should then view the source files themselves for more information about the available properties for each type of object.
Validation and Formatting:
To specify a valtype for a formfield, you should create an array with any/all of the following items:
'email'=>NULL, - This specifies that the value must be a valid e-mail address. This will also output an e-mail address (as an e-mail link) in the results. Also, if the nocopy property of the form/formset is not set to boolean true, a copy of the results will be sent to the address(es) specified in any field with this valtype set.
'phone'=>NULL, - This specifies that the value must be a valid phone number. This will also output a properly formatted phone number in the results. The number entered in the field must be either 7 or 10 digits (not including parens, hyphens or a leading 1). If it is not, it will throw an error. If the value is only 7 digits, the default area code (as set in the config file) will be prepended to the value.
'date'=>(bool) - false for a date, true for a date/time - This specifies that the value must be a valid date (as recognized by the PHP strtotime function). If it is not, an error will be thrown. This valtype will also return an AP style formatted date and/or date/time (if set to true).
'trimlen'=>(int) - length to which field value should be truncated
'zerofill'=>(int) - if the string length of the value is shorter than the integer specified with this valtype, it will be zero-filled from the left.
'maxlen'=>(int) - maximum length of string. If the value is longer than the max length, an error will be thrown.
'minlen'=>(int) - minimum length of string. If the value is shorter than the min length, an error will be thrown.
'exactlen'=>(int) - exact length field value should be. If the value is shorter or longer than the exact length, an error will be thrown.
'number'=>NULL - If the number valtype is specified, the value entered must be a valid number (according to the PHP is_numeric function). Otherwise, an error will be thrown.
'currency'=>NULL - If this valtype is specified, the value entered must be a valid number (according to the PHP is_numeric function). In addition, it will be returned in a currency format (currently only US currency format, with a US dollar symbol at the front, commas as thousands separator, a period as the decimal separator and two places after the decimal).
'cc=>NULL - If this valtype is specified, the value must be a valid credit card number. This valtype has not been tested yet, and should not be used on a production site without being properly tested. In addition, this valtype should probably not be used outside of the ccclass object, which is a collection of form fields (also not tested).
Notes about Checkboxes, Radio buttons, Select fields and Options:
1) Checkboxes and radio buttons are created using the checkgroup and radiogroup classes (respectively). They do not use standard labels the way other form fields do. Instead, the text you want displayed at the top of the groups of checkboxes or radio buttons should be specified using the title property.
2) Checkboxes within checkgroups, radio buttons within radiogroups and options within select elements are generated by setting the "options" property. The "options" property is an associative array with the "value" of the option/checkbox/radio button set as the "key" for the array and the text to be associated with the option/checkbox/radio button as the "value" of the array.
2a) To create a single optgroup to be used within a select element, you can insert a two-dimensional array within the options array that would look like: 'optgroup'=>array('options'=>array([value]=>[text],[value]=>[text]),'label'=>[label]). The key for this array item must be set to "optgroup". Because of that, only one optgroup can be created this way.
2b) To create multiple optgroups to use within a set of options, you will need to create an optgroup object for each optgroup. You will, unfortunately, also need to construct all of your other options (outside of the optgroups) by creating option objects for each. You will then add all of them to the myOpts property as an array, rather than adding them to the options array and having them constructed automatically through the constructor of the form field object.