Getting Started with ApPHP FormBuilder (v2.0.0 or above)

1. Common Notices.
2. Getting Started.
- 2.1 Setup FormBuilder.
- 2.2 Creating Form.
- 2.3 Adding Fields to Form.
- 2.4 Chaining Methods.
- 2.5 Full List of Fields' Options.
- 2.6 Sending Request Result with Email.
- 2.7 Rest of Form Options.
- 2.8 Filters.
- 2.9 Rest of Configuration Settings.
- 2.10 Validator Component.

Common Notices

• Use standard opening and closing tags <html>...</html>.
Enclose everything else in these otherwise your page may display incorrectly.
• Do not put ApPHP FormBuilder code into another HTML Form: <form>...</form>

Getting Started

2.1. Setup FormBuilder.

Make sure you define a valid relative(virtual) path to the formbuilder.php file.

## *** include FormBuilder
define('FB_DIR', '');
require_once(FB_DIR.'formbuilder.php');

Now all FormBuilder classes are loaded and can be used.

2.2. Creating Form.

Here is an example how to create a form:

## *** create form object
$form = new FB_Form($formName);

where $formName is a unique form name for the page.

2.3. Adding Fields to Form.

Now that the form is created we can add fields to it. This is how we add a simple text field:

## *** add text field to form
$form->AddTextField($name, $label);

where

$name is a unique for form name of an element. Same value will be assigned to "id" parameter of field.
$label is field description shown to user.

In the same way these fields can be added:

text field (method AddTextField($name, $label))
text area field (method AddTextArea($name, $label))
single select (method AddSingleSelect($name, $label, $optionsSet))
- $optionsSet is an array of options in format array($value => $option)
radio button (method AddRadioButton($name, $label, $optionsSet))
- $optionsSet is an array of options in format array($value => $option)
checkbox field (method AddCheckbox($name, $label, $isOn))
- $isOn indicates if the checkbox will be selected by default(set 0 or 1)
button (method AddButton($name, $value))
- $value is what going to be written on the button
submit button (method AddSubmitButton($name, $value))
- $value is what going to be written on the button
hidden field (method AddHidden($name, $value))
- $value field value to be sent by request

2.4. Chaining Methods

All field parameters return an object they where called by, so they can be chained. In other words you can write your code like this:

## *** code with chaining 
$form->AddTextField($name, $label)
     ->IsAlphabetic(1)
     ->IsRequired(1);

which is equivalent to

## *** code without chaining
$textField = $form->AddTextField($name, $label);
$textField->IsAlphabetic(1);
$textField->IsRequired(1);

2.5. Full List of Fields' Options

Further is a list of all fields' methods with these parameters. Methods marked with V2 are available only with ApPHP Validator version 2 or higher.

Basic methods. These methods are available with all fields.
- IsRequired($isRequired) indicates weather field value can be 0, null, "" or "0'
  -- $isRequired (int) flag for field to be required. To turn on set 1, to turn off set 0
- SetConfirmationFieldName($confirmationFieldName) set field name value of which should be equivalent to current
  -- $confirmationFieldName (string) field name value of which should be equivalent to current
- SetConfirmationValue($confirmationValue) set value equivalent to current field value
  -- $confirmationValue (mixed) value equivalent to current field value
Text field (method AddTextField($name, $label))
// View of field
- SetTitle($title) set html title for field
  -- $title (string) html title for field
- IsPassword() flag if this field is an password (html field will be of type "password")
- SetPlaceholder($placeholder)set a placeholder to be shown in field
  -- $placeholder (string) html placeholder to be shown in field
- SetFieldSet($fieldSet)set a html field set for field. Fields with same fieldset will be united together
  -- $fieldSet (string) html field set for field
// String value
- SetMinLength($min) set minimum length of string value in field
  -- $min (int) minimum length of string value
- SetMaxLength($max) set maximum length of string value in field
  -- $max (int) maximum length of string value
- IsAlphabetic() string value can contain only letters
- IsAlphanumeric() string value can contain letters and digits(is default)
- IsPointingAllowed() flag if pointing should be allowed for field. If only some signs should be used add them with AddAllowedSpecialChars() function.
- IsSpacesAllowed() flag if spaces can be used
- V2 SetRegExp($regExp) set regular expression to check the value.
  -- $regExp (string) regular expression to check the value
- V2 AddAllowedSpecialCharacters() add one or more special characters to be allowed in a string (this makes sense if IsPointingAllowed is set to 0). E.g. AddAllowedSpecialCharacters("_", "-");.
// Number value
- SetMinValue($min) set minimum for numeric value
  -- $min (int) minimum for numeric value
- SetMaxValue($min) set maximum for numeric value
  -- $max (int) maximum for numeric value
- IsInteger() numeric value should be an integer
- IsFloat() numeric value should be a float
- IsNumber() value is numeric
- V2 IsHex() flag if this field is a HEX
- V2 SetFloatPrecision($precision) set count of digits in decimal part
  -- $precision (int) count of digits in decimal part
- V2 SetAllowCommaAsDecimalSeparator() allow comma as well as dot to be a decimal separator
// Email
- IsEmail() flag if this field is an email
// URL
- IsUrl() flag if this field is an URL
// IP
- V2 IsIp() flag if this field is an IP
// Postcode
- V2 IsPostcode() flag if this field is a postcode
- V2 AddPostcodeCountries() add countries to check postcode (make sure those countries' postcode regular expression is set in "lib/modules/validator/lib/types/validatorTypePostcode.class.php"). To add a country use static parameter of ValidatorTypePostcode (e.g. ValidatorTypePostcode::$countryUS). You can add one country or several at a time (AddPostcodeCountries(ValidatorTypePostcode::$countryUS, ValidatorTypePostcode::$countryUK);)
// Phone number
- V2 IsPhoneNumber() flag if this field is a phone number
- V2 IsCellPhone($isCellPhone) flag if this field is a cell phone number or line phone number
// SSN
- V2 IsSsn() flag if this field is a SSN
Text area (method AddTextArea($name, $label) inherits from Text field all methods to work with Strings
// View of field
- SetCols($cols) sets number of columns in text area
  -- $cols (int) number of columns in text area
- SetRows($rows) sets number of rows in text area
  -- $rows (int) number of rows in text area
Checkbox (method AddCheckbox($name, $label, $isOn)
No specific methods
Radio button (method AddRadioButton($name, $label, $optionsSet)
// View of field
- SetShowVertical($showVertical) if radio buttons are to be shown one under another or one by another. By default 3 and more options are shown vertically
  -- $showVertical (int) set 1 for buttons to be shown vertically or 0 to be shown horizontally
Single select (method AddSingleSelect($name, $label, $optionsSet))
// View of field
- SetNullValue($nullValue) shows this value as first option in select with value "null". If field is required, then this options will be disabled (could not be chosen)
// Value of field
- SetValueToOptionsArray(array $optionsArray) set array in format array($value =>$option) to form a selection if you have not done it while adding field to a form.
  -- $optionsArray (array) array of options in format array($value =>$option)
- IsOneOfSet($validationSet) if you need value from some specific set and not all of optionsToValue array - add an array of needed values with this method
  -- $validationSet (array) array of values in format array($value1, $value2)
Hidden field (method AddHidden($name, $value) ) inherits all methods from Text field.
No specific methods.
Button (method AddButton($name, $value))
- AddJavaScriptOnEvent (array $javascriptEvent) add event as array
  -- $javascriptEvent (array) array in format array($event => $jsCode) (e.g. "onclick" => "alert('hello')")
Submit button (method AddSubmitButton($name, $value)) inherits methods from Button field
No specific methods.

2.6. Sending Request Result with Email

Result of a submitted form can be sent to one or more email addresses as a letter. In order to send the letter you can use further methods of FB_Form class:

SendResultAsEmail() sets that form result should be send as letter
AddEmailAddress() set required one or more addresses to send letter to
AddEmailContent($content) add optional content to letter
-- $content (string) text added to letter with request result
SetEmailSubject($subject) set email subject
-- $subject (string) email subject

Here is an example how letter can be set:

## *** Send form result encoded to JSON as email
$form = new FB_Form("name");
$form->SendResultAsEmail()
     ->AddEmailAddress("first@example.com", "second@example.com")
     ->AddEmailContent("Date: ".date("Y-m-d")
     ->SetEmailSubject("Form result"));

2.7. Rest of Form Options.

Form has several more methods you can use:

SetAction($action) set file to send you script after submit to. By default current page is an action. Do not use this option unless you are sure.
-- $action (string) file name to send form data to
SetMethod($method) set http method to send data
-- $method (string) you can set "POST" or "GET" method. By default "POST" method is used.
AddField(FB_BasicField $field) add any field object to form
-- $field field object to be added to form, should be a child of FB_BasicField.
AddHeader($header) set any text to be shown before form
-- $header (string) text to be shown before form
AddFooter($footer) set any text to be shown after form
-- $footer (string) text to be shown after form
GetResultArray() returns resulting array filter with all allowed filters
SetSuccessMsg($msg) set message to be shown when the form is successfully submitted
-- $msg (string) message to be shown when the form is successfully submitted
SetFailureMsg($msg) set message to be shown if the form failed to submit
-- $msg (string) message to be shown if the form failed to submit

2.8. Filters

Some filters could be used on submitted values. They can be turned On or Off in file "form_builder/lib/config.php" with constants:

FB_TRIM_FILTER_ON ("On" by default) trims spaces on the end of value
FB_SPECIAL_CHARS_FILTER_ON ("On" by default) encodes potentially special characters. For security reasons do not turn this off unless you know what you do.

2.9. Rest of Settings in "form_builder/lib/config.php"

Here is a list of settings' constants in "form_builder/lib/config.php":

FB_ENCODING ("UTF-8" by default) script encoding. Change it only if you are sure
FB_CSS_FILE ("styles/default/style.css" by default) current css file. If you change it, make sure a new css file exists in "form_builder/lib/css"
FB_DEBUG_MODE ("1" by default) if debug mode is on (not 0) error messages would be printed on screen and logged into file (if set). If off error messages will only be written into file (set in constant FB_LOG_FILE)
FB_LOG_FILE ("" by default) a path to log file error messages will be put into. Make sure the path to file is correct and directory and file have correct access rules

2.10. Validator component.

FormBuilder uses the ApPHP Validator component to check field values. Full functionality of FormBuilder is available only with Validator version 2 or higher. If you have FormBuilder with Validator v.1 and you want to change it to Validator v.2 simply put a Validator v.2 to folder "form_builder/lib/modules/validator/". Now all FormBuilder functionality will be available.

Members Login