Getting Started with ApPHP FormBuilder (v2.0.0 or above)
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.
- 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
-
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 withAddAllowedSpecialChars()
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("_", "-");
.
-
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
-
IsEmail()
flag if this field is an email
-
IsUrl()
flag if this field is an URL
-
V2
IsIp()
flag if this field is an IP
-
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 ofValidatorTypePostcode
(e.g.ValidatorTypePostcode::$countryUS
). You can add one country or several at a time (AddPostcodeCountries(ValidatorTypePostcode::$countryUS, ValidatorTypePostcode::$countryUK);
)
-
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
-
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)
-
SetValueToOptionsArray(array $optionsArray)
set array in formatarray($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 ofoptionsToValue
array - add an array of needed values with this method
--$validationSet
(array) array of values in formatarray($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 formatarray($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
## *** 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.