\ValidFormBuilderValidForm

ValidForm Builder main class - all the magic starts here.

Check out some of the following examples to get started

Example; Create a ValidForm Builder instance

$objForm = new ValidForm("cool_new_form", "Please fill out my cool form", "/awesome-submits");

Example 2; Add a field

Check out the constants section starting with \ValidFormBuilder\ValidForm::VFORM_BOOLEAN for more field types

$objForm->addField(
    "first-name",
    "First name",
    ValidForm::VFORM_STRING,
    array(
        // Make this field required
        "required" => true
    ),
    array(
        // Show this error to indicate this is an required field if no value is submitted
        "required" => "This field is required"
    )
);

Example 3; Using \ValidFormBuilder\ValidForm::setDefaults() to set default values on form fields

//*** Add a checklist
$objCheck = $objForm->addField("cool", "Cool checklist", ValidForm::VFORM_CHECK_LIST);
$objCheck->addField("Option 1", "option1");
$objCheck->addField("Option 2", "option2");
$objCheck->addField("Option 3", "option3");

// Add a standard string field
$objCheck = $objForm->addField("cool-text", "Coolest PHP Library", ValidForm::VFORM_STRING);

$objForm->setDefaults([
    // Set value of field 'cool text' to 'ValidForm Builder'
    "cool-text" => "ValidForm Builder",
    // Check options 2 and 3
    "cool" => ["option2", "option3"]
]);

Summary

Methods
Properties
Constants
__get()
__set()
__call()
__construct()
setDefaults()
setAutoComplete()
addHtml()
addNavigation()
addFieldset()
addHiddenField()
renderField()
addField()
addParagraph()
addButton()
addArea()
addMultiField()
addJSEvent()
toHtml()
fieldsToHtml()
toJs()
elementsToJs()
serialize()
unserialize()
isSubmitted()
getCachedFields()
getFields()
getValidField()
getInvalidFields()
isValid()
valuesAsHtml()
fieldsetAsHtml()
generateId()
getUniqueId()
get()
getIsSet()
getHttpBodyValue()
getStrippedClassName()
getDescription()
setDescription()
getMeta()
setMeta()
getDefaults()
getAction()
setAction()
setUseCsrfProtection()
getSubmitLabel()
setSubmitLabel()
getJsEvents()
setJsEvents()
getDisplayErrors()
setDisplayErrors()
getElements()
setElements()
getName()
setName()
getMainAlert()
setMainAlert()
getRequiredStyle()
setRequiredStyle()
getNoValuesMessage()
setNoValuesMessage()
setCachedFields()
setUniqueId()
No public properties found
VFORM_STRING
VFORM_TEXT
VFORM_NUMERIC
VFORM_INTEGER
VFORM_WORD
VFORM_EMAIL
VFORM_PASSWORD
VFORM_SIMPLEURL
VFORM_FILE
VFORM_BOOLEAN
VFORM_RADIO_LIST
VFORM_CHECK_LIST
VFORM_SELECT_LIST
VFORM_PARAGRAPH
VFORM_CURRENCY
VFORM_DATE
VFORM_CUSTOM
VFORM_CUSTOM_TEXT
VFORM_HTML
VFORM_URL
VFORM_HIDDEN
VFORM_COMPARISON_EQUAL
VFORM_COMPARISON_NOT_EQUAL
VFORM_COMPARISON_EMPTY
VFORM_COMPARISON_NOT_EMPTY
VFORM_COMPARISON_LESS_THAN
VFORM_COMPARISON_GREATER_THAN
VFORM_COMPARISON_LESS_THAN_OR_EQUAL
VFORM_COMPARISON_GREATER_THAN_OR_EQUAL
VFORM_COMPARISON_CONTAINS
VFORM_COMPARISON_DOES_NOT_CONTAIN
VFORM_COMPARISON_STARTS_WITH
VFORM_COMPARISON_ENDS_WITH
VFORM_COMPARISON_REGEX
VFORM_COMPARISON_IN_ARRAY
VFORM_COMPARISON_NOT_IN_ARRAY
VFORM_MATCH_ALL
VFORM_MATCH_ANY
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Constants

VFORM_STRING

VFORM_STRING = 1 : \ValidFormBuilder\number

Input type[text] with standard string validation

VFORM_TEXT

VFORM_TEXT = 2 : \ValidFormBuilder\number

Textarea element type

VFORM_NUMERIC

VFORM_NUMERIC = 3 : \ValidFormBuilder\number

Input type[text] with numeric validation

VFORM_INTEGER

VFORM_INTEGER = 4 : \ValidFormBuilder\number

Input type[text] with integer validation

VFORM_WORD

VFORM_WORD = 5 : \ValidFormBuilder\number

Input type[text] with single word validation

VFORM_EMAIL

VFORM_EMAIL = 6 : \ValidFormBuilder\number

Input type[text] with email validation

VFORM_PASSWORD

VFORM_PASSWORD = 7 : \ValidFormBuilder\number

Input type[password]

VFORM_SIMPLEURL

VFORM_SIMPLEURL = 8 : \ValidFormBuilder\number

Input type[text] with basic URL validation

VFORM_FILE

VFORM_FILE = 9 : \ValidFormBuilder\number

Input type[file]

VFORM_BOOLEAN

VFORM_BOOLEAN = 10 : \ValidFormBuilder\number

Input type[radio]

VFORM_RADIO_LIST

VFORM_RADIO_LIST = 12 : \ValidFormBuilder\number

Group element. Each added element is an input[type=radio]

VFORM_CHECK_LIST

VFORM_CHECK_LIST = 13 : \ValidFormBuilder\number

Group element. Each added element is an input[type=checkbox]

VFORM_SELECT_LIST

VFORM_SELECT_LIST = 14 : \ValidFormBuilder\number

Group element. Each added element is an option element

VFORM_PARAGRAPH

VFORM_PARAGRAPH = 15 : \ValidFormBuilder\number

Not an element. This creates a paragraph in between form fields.

VFORM_CURRENCY

VFORM_CURRENCY = 16 : \ValidFormBuilder\number

Input element

VFORM_DATE

VFORM_DATE = 17 : \ValidFormBuilder\number

Input type[text] with European date validation (dd/mm/yyyy)

VFORM_CUSTOM

VFORM_CUSTOM = 18 : \ValidFormBuilder\number

Input type[text] with custom regular expression validation

VFORM_CUSTOM_TEXT

VFORM_CUSTOM_TEXT = 19 : \ValidFormBuilder\number

Textarea with custom regular expression validation

VFORM_HTML

VFORM_HTML = 20 : \ValidFormBuilder\number

Textarea with basic input validation + HTML tags allowed

VFORM_URL

VFORM_URL = 21 : \ValidFormBuilder\number

Input type[text] with url validation

VFORM_HIDDEN

VFORM_HIDDEN = 22 : \ValidFormBuilder\number

Input type[hidden]

VFORM_COMPARISON_EQUAL

VFORM_COMPARISON_EQUAL = "equal" : string

Check if this value is equal (case insensitive)

VFORM_COMPARISON_NOT_EQUAL

VFORM_COMPARISON_NOT_EQUAL = "notequal" : string

Check if this value is **not** equal (case insensitive)

VFORM_COMPARISON_EMPTY

VFORM_COMPARISON_EMPTY = "empty" : string

Check if this value is empty

VFORM_COMPARISON_NOT_EMPTY

VFORM_COMPARISON_NOT_EMPTY = "notempty" : string

Check if this value is **not** empty

VFORM_COMPARISON_LESS_THAN

VFORM_COMPARISON_LESS_THAN = "lessthan" : string

Check if this value is less than

VFORM_COMPARISON_GREATER_THAN

VFORM_COMPARISON_GREATER_THAN = "greaterthan" : string

Check if this value is greater than

VFORM_COMPARISON_LESS_THAN_OR_EQUAL

VFORM_COMPARISON_LESS_THAN_OR_EQUAL = "lessthanorequal" : string

Check if this value is less than or equal

VFORM_COMPARISON_GREATER_THAN_OR_EQUAL

VFORM_COMPARISON_GREATER_THAN_OR_EQUAL = "greaterthanorequal" : string

Check if this value is greater than or equal

VFORM_COMPARISON_CONTAINS

VFORM_COMPARISON_CONTAINS = "contains" : string

Check if the value contains this string (case insensitive)

VFORM_COMPARISON_DOES_NOT_CONTAIN

VFORM_COMPARISON_DOES_NOT_CONTAIN = "doesnotcontain" : string

Check if the value does not contain this string (case insensitive)

VFORM_COMPARISON_STARTS_WITH

VFORM_COMPARISON_STARTS_WITH = "startswith" : string

Check if the value **starts** with this string

VFORM_COMPARISON_ENDS_WITH

VFORM_COMPARISON_ENDS_WITH = "endswith" : string

Check if the value **ends** with this string

VFORM_COMPARISON_REGEX

VFORM_COMPARISON_REGEX = "regex" : string

Check if the value matches your own custom regular expression

VFORM_COMPARISON_IN_ARRAY

VFORM_COMPARISON_IN_ARRAY = "in_array" : string

Check if the value matches your own custom regular expression

VFORM_COMPARISON_NOT_IN_ARRAY

VFORM_COMPARISON_NOT_IN_ARRAY = "not_in_array" : string

Check if the value matches your own custom regular expression

VFORM_MATCH_ALL

VFORM_MATCH_ALL = "all" : string

ValidForm Condition match

Match all of the defined conditions

VFORM_MATCH_ANY

VFORM_MATCH_ANY = "any" : string

ValidForm Condition match

Match any of the defined conditions

Methods

__get()

__get(string  $property) 

Magic getter method

Parameters

string $property

Throws

\BadMethodCallException

__set()

__set(string  $property, mixed  $value) 

Magic setter method

Parameters

string $property
mixed $value

Throws

\BadMethodCallException

__call()

__call(string  $method, mixed  $values) 

Magic caller method

Parameters

string $method
mixed $values

Throws

\BadMethodCallException

__construct()

__construct(string  $name, string  $description = null, string  $action = null, array  $meta = array()) 

Create a new ValidForm Builder instance

Parameters

string $name

The form's name. This will also be the value of the name attribute in the generated HTML. Note: At this moment, it is mandatory to enter a name even though the API states that it is optional. Check issue 8 for more details.

string $description

Optional. A descriptive text shown above the form fields.

string $action

The generated form element's action attribute.

array $meta

Custom form meta array

setDefaults()

setDefaults(array  $arrDefaults = array()) 

Use an array to set default values on all the forms children.

The array's keys should be the form name to set the default value of, the value is the actual value or values to set.

Example 1 - Basic defaults:

//*** The form
$objCheck = $objForm->addField("cool", "Coolest PHP Library", ValidForm::VFORM_STRING);

//*** Set field 'cool' default value to "ValidForm Builder"
$objForm->setDefaults([
    "cool" => "ValidForm Builder"
]);

Example 2 - An array of defaults:

//*** The form
$objCheck = $objForm->addField("cool", "Cool checklist", ValidForm::VFORM_CHECK_LIST);
$objCheck->addField("Option 1", "option1");
$objCheck->addField("Option 2", "option2");
$objCheck->addField("Option 3", "option3");

$objCheck = $objForm->addField("cool-text", "Coolest PHP Library", ValidForm::VFORM_STRING);

//*** Check options 2 and 3 by default using setDefaults()
$objForm->setDefaults([
    "cool-text" => "ValidForm Builder",
    "cool" => ["option2", "option3"]
]);

Parameters

array $arrDefaults

The array of default values. Keys are field names, values strings or arrays

Throws

\InvalidArgumentException

setAutoComplete()

setAutoComplete(  $blnValue) 

Parameters

$blnValue

addHtml()

addHtml(string  $html, array  $meta = array()) : \ValidFormBuilder\StaticText

Injects a string in the form.

Use this to add an extra string in the form. For instance, you can create an input field like this:

Enter the amount:   $ _____

In this example, we used StaticText to inject the dollar sign before our input field.

Parameters

string $html

The string or HTML code to inject

array $meta

Returns

\ValidFormBuilder\StaticText

addNavigation()

addNavigation(array  $meta = array()) : \ValidFormBuilder\Navigation

Add 'navigation' to the form. By navigation we mean a 'navigation div' at the buttom of the form containing the submit button. This method is optional for customization purposes -- navigation is created automatically.

Parameters

array $meta

Array with meta data. Only the "style" attribute is supported as for now.

Returns

\ValidFormBuilder\Navigation

addFieldset()

addFieldset(string  $header = null, string  $noteHeader = null, string  $noteBody = null, array  $meta = array()) : \ValidFormBuilder\Fieldset

Add a fieldset to the form field collection

Example:

$objForm->addFieldset("Header for fieldset", "Note", "Cool fields contained by fieldset.");

Parameters

string $header

The header for this fieldset

string $noteHeader

An optional header for the 'note' block on the side of this fieldset

string $noteBody

The optional body for the 'note block on the side of this fieldset

array $meta

The meta array

Returns

\ValidFormBuilder\Fieldset

addHiddenField()

addHiddenField(string  $name, string  $type, array  $meta = array(), boolean  $blnJustRender = false) : \ValidFormBuilder\Hidden

Add a hidden input field to the form collection.

Hidden fields can be used for example to inject custom values in your post data and still have them validated using ValidForm Builder.

Parameters

string $name

The hidden field's name attribute

string $type

Define a validation type using one of the ValidForm::VFORM_ constants. This does not influence the fact that you're creating a hidden field. This is only used for validation of the hidden field's content.

array $meta

Optional meta array

boolean $blnJustRender

If true, only create a {@link \ValidFormBuilder\Hidden} instance and return it. When false, this {@link \ValidFormBuilder\Hidden} instance is added to the internal elements collection and will be parsed when toHtml() is called.

Returns

\ValidFormBuilder\Hidden

renderField()

renderField(string  $name, string  $label, integer  $type, array  $validationRules, array  $errorHandlers, array  $meta) : \ValidFormBuilder\Element

Use this utility method to only render \ValidFormBuilder\Element instances of the defined types.

Elements rendered with this method aren't added to the internal elements collection.

Parameters

string $name

The element's name

string $label

The element's label

integer $type

The element's validation type

array $validationRules

Optional.Custom validation rules array

array $errorHandlers

Custom error handling array

array $meta

Optional. Meta data array

Returns

\ValidFormBuilder\Element

Returns null when no valid type is defined

addField()

addField(string  $name, string  $label, integer  $type, array  $validationRules = array(), array  $errorHandlers = array(), array  $meta = array(), boolean  $blnJustRender = false) : \ValidFormBuilder\Element

Add a new element to the internal elements collection

Example; add a text field:

$objForm->addField(
    "first-name",
    "First name",
    ValidForm::VFORM_STRING,
    array(
        // Make this field required
        "required" => true
    ),
    array(
        // Show this error to indicate this is an required field if no value is submitted
        "required" => "This field is required"
    )
);

Parameters

string $name

The element's name

string $label

The element's label

integer $type

The element's validation type

array $validationRules

Optional.Custom validation rules array

array $errorHandlers

Custom error handling array

array $meta

Optional. Meta data array

boolean $blnJustRender

When true, the element is not added to the internal elements collection. addField() with $blnJustRender set to true is exactly the same as calling ValidForm::renderField()

Returns

\ValidFormBuilder\Element

Returns null when no valid type is defined

addParagraph()

addParagraph(string  $strBody, string  $strHeader = "", array  $meta = array()) : \ValidFormBuilder\Paragraph

Adds a \ValidFormBuilder\Paragraph object to the internal elements collection.

This renders a paragraph inside the form. Formfields can be added before and after the paragraph. Example:

$objForm->addField("name", "Your Name", ValidForm::VFORM_STRING);
$objForm->addParagraph("Next, you should enter your last name.", "Enter your name!");
$objForm->addField("last-name", "Last Name", ValidForm::VFORM_STRING);

Parameters

string $strBody

Paragraph body

string $strHeader

Optional header above the paragraph

array $meta

Custom meta array

Returns

\ValidFormBuilder\Paragraph

addButton()

addButton(string  $strLabel, array  $arrMeta = array()) : \ValidFormBuilder\Button

Adds a <button> element to the internal fields collection.

For an example; see \ValidFormBuilder\Button

Parameters

string $strLabel

The button's label

array $arrMeta

The meta array

Returns

\ValidFormBuilder\Button

addArea()

addArea(string  $label = null, boolean  $active = false, string  $name = null, boolean  $checked = false, array  $meta = array()) : \ValidFormBuilder\Area

Add an area to the internal elements collection.

See \ValidFormBuilder\Area for examples

Parameters

string $label

The title of this area

boolean $active

If true, the title has a checkbox which can enable or disable all child elements

string $name

The ID of this area

boolean $checked

Use in combination with $active; if true, the checkbox will be checked by default

array $meta

The meta array

Returns

\ValidFormBuilder\Area

addMultiField()

addMultiField(string  $label = null, array  $meta = array()) : \ValidFormBuilder\MultiField

Create a Multifield element

Multifield elements allow you to combine multiple fields horizontally with one label. For example, create a first name + last name field with label "Full name"

$objMulti = $objForm->addMultifield("Full name");
// Note: when using addField on a multifield, we don't set a label!
$objMulti->addField(
    "first-name",
    ValidForm::VFORM_STRING,
    array(),
    array(),
    // Keep it short, this is just a first name field
    array("style" => "width: 50px")
);
$objMulti->addField("last-name", ValidForm::VFORM_STRING);

You can also combine select elements to create a date picker:

$objMulti = $objForm->addMultiField("Birthdate");
$objMulti->addField(
    "year",
    ValidForm::VFORM_SELECT_LIST,
    array(),
    array(),
    array(
        "start" => 1920,
        "end" => 2014,
        // 'fieldstyle' gets applied on the <select>
        // regular 'style' applies on the wrapping <div>
        "fieldstyle" => "width: 75px"
    )
);
$objMulti->addField(
    "month",
    ValidForm::VFORM_SELECT_LIST,
    array(),
    array(),
    array(
        "start" => 01,
        "end" => 12,
        "fieldstyle" => "width: 75px"
    )
);
$objMulti->addField(
    "day",
    ValidForm::VFORM_SELECT_LIST,
    array(),
    array(),
    array(
        "start" => 1,
        "end" => 31,
        "fieldstyle" => "width: 75px"
    )
);

Parameters

string $label
array $meta

The meta array

Returns

\ValidFormBuilder\MultiField

addJSEvent()

addJSEvent(string  $strEvent, string  $strMethod) 

Add a custom javascript event with corresponding callback function

With this method you can either register a custom callback function on one of the predefined custom events or you can register the callback function on a jQuery bindable event (e.g. jQuery().bind(eventName, callback)).

These are predefined event hooks in the ValidForm Builder client-side library:

  • beforeSubmit
  • beforeNextPage
  • afterNextPage
  • beforePreviousPage
  • afterPreviousPage
  • beforeAddPreviousButton
  • afterAddPreviousButton
  • beforeShowPage
  • afterShowPage
  • beforeAddPageNavigation
  • afterAddPageNavigation
  • beforeDynamicChange
  • afterDynamicChange
  • afterValidate

Parameters

string $strEvent

The event name

string $strMethod

The name of the callback function

toHtml()

toHtml(boolean  $blnClientSide = true, boolean  $blnForceSubmitted = null, string  $strCustomJs = "") : string

Generate HTML output - build form

Parameters

boolean $blnClientSide

Render javascript code or not, defaults to true

boolean $blnForceSubmitted

This forces the form rendering as if the fields are submitted

string $strCustomJs

Inject custom javascript to be executed while initializing ValidForm Builder client-side.

Returns

string —

Generated HTML output

fieldsToHtml()

fieldsToHtml(boolean  $blnForceSubmitted = false, boolean  $blnNavigation = false) : string

This method generates HTML output for the current internal elements collection.

This method is mostly used internally in the library and it's therefore not recommended to use this except for these rare occasions when you only want the rendered fields an not all the meta surrounding the fields like the form tag, description element and form error message.

Parameters

boolean $blnForceSubmitted

This forces the form rendering as if the fields are submitted

boolean $blnNavigation

This is a reference returning true if the form contains a navigation element

Returns

string —

Generated HTML output

toJs()

toJs(string  $strCustomJs = "") : string

Generate the Javascript output only.

This is particulary useful when using ValidForm Builder in combination with AJAX form handling. In that case you don't want to output the HTML together with the javascript.

Parameters

string $strCustomJs

Inject custom javascript to be executed while initializing ValidForm Builder client-side.

Returns

string

elementsToJs()

elementsToJs(boolean  $blnRawJs = false) : string

Generate the Javascript output only for the fields and conditions.

This is particulary useful when using ValidForm Builder in combination with AJAX form handling. You can inject new fields and field logic into an existing ValidForm and all validation will be handled by that "parent" form.

Parameters

boolean $blnRawJs

Return javascript without the surrounding