VFORM_STRING
VFORM_STRING = 1 : \ValidFormBuilder\number
Input type[text] with standard string validation
ValidForm Builder main class - all the magic starts here.
Check out some of the following examples to get started
$objForm = new ValidForm("cool_new_form", "Please fill out my cool form", "/awesome-submits");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"
)
);//*** 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"]
]);__construct(string $name, string $description = null, string $action = null, array $meta = array())
Create a new ValidForm Builder instance
| 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 |
| array | $meta | Custom form meta array |
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"]
]);| array | $arrDefaults | The array of default values. Keys are field names, values strings or arrays |
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.
| string | $html | The string or HTML code to inject |
| array | $meta |
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.
| array | $meta | Array with meta data. Only the "style" attribute is supported as for now. |
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.");| 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 |
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.
| string | $name | The hidden field's |
| string | $type | Define a validation type using one of the |
| 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 |
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.
| 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 null when no valid type is defined
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"
)
);| 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.
|
Returns null when no valid type is defined
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);| string | $strBody | Paragraph body |
| string | $strHeader | Optional header above the paragraph |
| array | $meta | Custom meta array |
addButton(string $strLabel, array $arrMeta = array()) : \ValidFormBuilder\Button
Adds a <button> element to the internal fields collection.
For an example; see \ValidFormBuilder\Button
| string | $strLabel | The button's label |
| array | $arrMeta | The meta array |
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
| string | $label | The title of this area |
| boolean | $active | If |
| string | $name | The ID of this area |
| boolean | $checked | Use in combination with |
| array | $meta | The meta array |
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"
)
);| string | $label | |
| array | $meta | The meta array |
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:
| string | $strEvent | The event name |
| string | $strMethod | The name of the callback function |
toHtml(boolean $blnClientSide = true, boolean $blnForceSubmitted = null, string $strCustomJs = "") : string
Generate HTML output - build form
| 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. |
Generated HTML output
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.
| 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 |
Generated HTML output
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.
| string | $strCustomJs | Inject custom javascript to be executed while initializing ValidForm Builder client-side. |
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.
| boolean | $blnRawJs | Return javascript without the surrounding |