HexagonJS
Edit Page
Form Builder
Provides an api for building forms in javascript.
Examples

HTML

<form id="form"></form>

JavaScript

var form = new hx.Form('#form')
  .addText('Text', { required: true, placeholder: 'Name' })
  .addTextArea('Text Area', { placeholder: 'Name' })
  .addEmail('Email', { required: true, placeholder: 'your.name@ocado.com' })
  .addUrl('Url', { placeholder: 'http://www.example.co.uk/' }) // Allows blank or valid URL (with http:// prefix)
  .addNumber('Number', {required: true})
  .addPicker('Select', ['red', 'green', 'blue'])
  .addCheckbox('Checkbox')
  .addPassword('Password')
  .addRadio('Radio', ['One', 'Two', 'Three'])
  .addTagInput('Tag Input')
  .addFileInput('File Input')
  .addDatePicker('Date Picker')
  .addTimePicker('Time Picker')
  .addDateTimePicker('Date Time Picker')
  .addButton('Button', () => console.log('Clicked Button'))
  .addSubmit('Submit', 'fa fa-check')
  .on('submit', function (data) {console.log(data)})
Api
Prototypes
hx.FormextendsEventEmitter
Used for building forms.
Constructors
hx.FormselectorHTMLElement / String
Creates a new Form object that is linked to a form element on the page.
Arguments
selectorHTMLElement / String
An HTMLElement or CSS selector that uniquely identifies your form.
Add Component Methods
Methods that add components to the form
addTextnameStringoptionsObjectFormupdated
Adds a text field to the form.
Arguments
nameString
The field name.
options
The options to use when creating the text field.
Properties
autocompleteDataData / Functionadded
The data to use for auto complete suggestions. Can be either an array of data or a function that returns data. For a more detailed explanation, see the Autocomplete.
autocompleteOptionsadded
The options to use for the auto complete. For a more detailed explanation, see the Autocomplete page.
autoCompleteDataData / Functiondeprecated
Deprecated
This option has been replaced with the lowercase variant autocompleteData
The data to use for auto complete suggestions. Can be either an array of data or a function that returns data. For a more detailed explanation, see the Auto Complete page.
autoCompleteOptionsdeprecated
Deprecated
This option has been replaced with the lowercase variant autocompleteOptions
The options to use for the auto complete. For a more detailed explanation, see the Auto Complete page.
attrsArray
Additional attributes to give the text input. This should be an array of objects with type and value properties.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
placeholderString
The placeholder text to use - this will appear as a greyed out suggestion/hint in the input box.
requiredBoolean
Whether or not this is a required field.
typeString
The type of text field - the default is 'text'.
validatoreventEventString
A function that is called when the 'oninput' function is called. It is passed the event object and should return an error message as a string:
var validator = function(e){
  if(e.target.value.length < 5){
    "Please enter text longer than 5 characters"
  }
}
Arguments
eventEvent
The input event that was emiited by the input element.
Returns
The error string to display if the string did not validate, or undefined if the contents of the input was valid.
valueAny
The value to set for this field
Returns
Form
This Form
addDatePickernameStringoptionsObjectForm
Adds a date picker to the form.
Arguments
nameString
The field name.
options
The options to use when creating the field.
Properties
datePickerOptionsObjec
The options to use for the date picker component. See the Date Picker constructor for the available options.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
endDateDate
The selected end date to use when selectRange is true. Both startDate and endDate must be defined for this to have an effect.
Default: Today
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
startDateDate
The selected start date to use when selectRange is true. Both startDate and endDate must be defined for this to have an effect.
Default: Today
validEndDate
The valid end date for the date picker. The user will not be able to select dates after this date.
validStartDate
The valid start date for the date picker. The user will not be able to select dates before this date.
Returns
Form
This Form
addEmailnameStringoptionsObjectForm
Adds an email field to the form.
Arguments
nameString
The field name.
options
The options to use when creating the email field.
Properties
attrsArray
Additional attributes to give the text input. This should be an array of objects with type and value properties.
autoCompleteDataData / Function
The data to use for auto complete suggestions. Can be either an array of data or a function that returns data. For a more detailed explanation, see the Auto Complete page.
autoCompleteOptions
The options to use for the auto complete. For a more detailed explanation, see the Auto Complete page.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
placeholderString
The placeholder text to use - this will appear as a greyed out suggestion/hint in the input box.
requiredBoolean
Whether or not this is a required field.
validatoreventEventString
A function that is called when the 'oninput' function is called. It is passed the event object and should return an error message as a string:
var validator = function(e){
  if(e.target.value.length < 5){
    "Please enter text longer than 5 characters"
  }
}
Arguments
eventEvent
The input event that was emiited by the input element.
Returns
The error string to display if the string did not validate, or undefined if the contents of the input was valid.
valueAny
The value to set for this field
Returns
Form
This Form
addNumbernameStringoptionsObjectForm
Adds a number field to the form.
Arguments
nameString
The field name.
options
The options to use when creating the number field.
Properties
attrsArray
Additional attributes to give the text input. This should be an array of objects with type and value properties.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
The maximum value the number input should allow. By default there is no maximum.
The minimum value the number input should allow. By default there is no minimum.
placeholderString
The placeholder text to use - this will appear as a greyed out suggestion/hint in the input box.
requiredBoolean
Whether or not this is a required field.
stepNumber
Specifies the legal number intervals for the input field. The default is 'any'.
validatoreventEventString
A function that is called when the 'oninput' function is called. It is passed the event object and should return an error message as a string:
var validator = function(e){
  if(e.target.value.length < 5){
    "Please enter text longer than 5 characters"
  }
}
Arguments
eventEvent
The input event that was emiited by the input element.
Returns
The error string to display if the string did not validate, or undefined if the contents of the input was valid.
valueAny
The value to set for this field
Returns
Form
This Form
addPasswordnameStringoptionsObjectForm
Adds a password field to the form.
Arguments
nameString
The field name.
options
The options to use when creating the password field.
Properties
attrsArray
Additional attributes to give the text input. This should be an array of objects with type and value properties.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
placeholderString
The placeholder text to use - this will appear as a greyed out suggestion/hint in the input box.
requiredBoolean
Whether or not this is a required field.
validatoreventEventString
A function that is called when the 'oninput' function is called. It is passed the event object and should return an error message as a string:
var validator = function(e){
  if(e.target.value.length < 5){
    "Please enter text longer than 5 characters"
  }
}
Arguments
eventEvent
The input event that was emiited by the input element.
Returns
The error string to display if the string did not validate, or undefined if the contents of the input was valid.
valueAny
The value to set for this field
Returns
Form
This Form
addUrlnameStringoptionsObjectForm
Adds a url field to the form. The url field only allows addresses with the http:// or https:// prefix, for other url types, a text field should be used with a custom validator.
Arguments
nameString
The field name.
options
The options to use when creating the email field.
Properties
attrsArray
Additional attributes to give the text input. This should be an array of objects with type and value properties.
autoCompleteDataData / Function
The data to use for auto complete suggestions. Can be either an array of data or a function that returns data. For a more detailed explanation, see the Auto Complete page.
autoCompleteOptions
The options to use for the auto complete. For a more detailed explanation, see the Auto Complete page.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
placeholderString
The placeholder text to use - this will appear as a greyed out suggestion/hint in the input box.
requiredBoolean
Whether or not this is a required field.
validatoreventEvent
A function that is called when the 'oninput' function is called. It is passed the event object and should return an error message as a string:
var validator = function(e){
  if(e.target.value.length < 5){
    "Please enter text longer than 5 characters"
  }
}
Arguments
eventEvent
The input event that was emiited by the input element.
valueAny
The value to set for this field
Returns
Form
This Form
addCheckboxnameStringoptionsObjectForm
Adds a checkbox field to the form
Arguments
nameString
The field name.
options
The options to use when adding the checkbox
Properties
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
requiredBoolean
Whether or not this is a required field. The default is false. If set to required, the user must tick the box before the form can be submitted.
valueAny
The value to set for this field
Returns
Form
This Form
addRadionameStringvaluesArray[String]optionsObjectForm
Adds a radio field to the form.
Arguments
nameString
The field name.
valuesArray[String]
An array that contains the list of labels for the radio options.
options
The options to use when adding the radio.
Properties
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
requiredBoolean
Whether or not this is a required field
valueAny
The value to set for this fiel d
Returns
Form
This Form
addTagInputnameStringoptionsObjectForm
Adds a hx.TagInput field.
Arguments
nameString
The field name.
options
The options to use when adding the tag input.
Properties
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
placeholderString
The placeholder text for the tag input
requiredBoolean
Whether the tag input must have at least one value entered.
tagInputOptions
The options to use for the tg input component. See the tag input constructor for the available options.
Returns
Form
This Form
addTimePickernameStringoptionsObjectForm
Adds a time picker to the form.
Arguments
nameString
The field name.
options
The options to use when creating the field.
Properties
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
timePickerOptions
The options to use for the time picker component. See the Time Picker constructor for the available options.
Returns
Form
This Form
addDateTimePickernameStringoptionsObjectForm
Adds a date time picker to the form.
Arguments
nameString
The field name.
options
The options to use when creating the field.
Properties
closeOnSelectBoolean
Whether to close the date time picker when a date has been selected.
Default: true
dateTimePickerOptions
The options to use for the time picker component. See the Date Time Picker constructor for the available options.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
Returns
Form
This Form
addTextAreanameStringoptionsObjectForm
Adds a textarea field to the form.
Arguments
nameString
The field name.
options
The options to use when creating the textarea field.
Properties
attrsArray
Additional attributes to give the textarea input. This should be an array of objects with type and value properties.
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
placeholderString
The placeholder text to use - this will appear as a greyed out suggestion/hint in the input box.
requiredBoolean
Whether or not this is a required field.
typeString
The type of text field - the default is 'textarea'.
validatoreventEventString
A function that is called when the 'oninput' function is called. It is passed the event object and should return an error message as a string:
var validator = function(e){
  if(e.target.value.length < 5){
    "Please enter text longer than 5 characters"
  }
}
Arguments
eventEvent
The input event emitted from the textarea.
Returns
The error string to display if the string did not validate, or undefined if the contents of the input was valid.
valueAny
The value to set for this field
Returns
Form
This Form
addPickernameStringvaluesArray[String / Object]optionsObjectForm
Adds a picker to the form.
Arguments
nameString
The field name.
An array of the possible options in the picker. It can be an array of strings or an array of objects, e.g:
[ "Hue", "Saturation", "Lightness"]
var values = [
  { text: 'Hue', value: 'hue' } ,
  { text: 'Saturation', value: 'saturation'},
  { text: 'Lightness', value: 'lightness'}
];
form.addSelect('Select', values)
options
Properties
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
pickerOptions
The options to use for the picker component. See the picker constructor for the available options.
requiredBoolean
Whether or not this is a required field.
When the value is 'false', the picker object will start with a blank value but is not required to be selected.
When the value is 'true', the picker object will start with a blank value and will not validate until a user has selected an option.
When the value is not defined, the picker behaves as normal.
Returns
Form
This Form
addSubmittextStringiconStringsubmitActionFunctionoptionsObjectForm
Adds a submit button to the form
Arguments
textString
The text to give the button
iconString
The icon class for the button's icon
submitActionformForm
The function to call when the form is submitted instead of calling form.submit() . Useful for setting custom error messages for properties before submitting the form.
Arguments
formForm
The form being submitted
options
Properties
disabledBoolean
Whether the submit button should be disabled
Default: false
hiddenBoolean
Whether the submit button should be hidden
Default: false
The key to use when hiding/showing the submit button
Default: The text argument
Returns
Form
This Form
addButtontextStringactionFunctionoptionsObjectForm
Adds a button to the bottom of the form.
All added buttons will display at the bottom of the form in the order they are added.
Arguments
textString
The text to display on the button
action
The action to perform when the button is clicked
options
Properties
buttonTypeString
The type of the button
Default: 'button'
contextString
The context to apply to the button.
Default: 'action'
disabledBoolean
Whether the button should be disabled
Default: false
hiddenBoolean
Whether the button should be hidden
Default: false
iconString
The icon class for the button's icon
The property name to map the button to when disabling/enabling the button.
Default: The text argument
Returns
Form
This Form
addTogglenameoptionsObject
Adds a hx.Toggle field.
Arguments
name
The field name
options
The options to use when adding the Toggle.
Properties
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
toggleOptions
The options to use for the Toggle component.
See the hx.Toggle prototype constructor for the available options.
addFileInputnameoptionsObject
Adds a hx.FileInput field.
Arguments
name
The field name
options
The options to use when adding the FileInput.
Properties
disabledBoolean
Whether the property should be disabled as it's initial state. This can also be toggled with the disabled(property, disabled) method.
Default: false
fileInputOptions
The options to use for the FileInput component.
See the hx.FileInput prototype constructor for the available options.
hiddenBoolean
Whether the property should be hidden as it's initial state. This can also be toggled with the hidden(property, hidden) method.
Default: false
The property name to map the input value to when filling the form and when getting the data.
addAutocompletePickernameStringvaluesArray / FunctionoptionsObjectForm
Adds an autocomplete picker to the form.
Arguments
nameString
The field name.
valuesArray / Function
An array of items or a function that supplies a list of items. See the
options
Properties
autocompletePickerOptions
The options to use for the picker component. See the autocomplete-pickerconstructor for the available options.
disabledBoolean
Whether the picker should be disabled.
The property name to map the input value to when filling the form and when getting the data.
requiredBoolean
Whether or not this is a required field.
When the value is 'false', the picker object will start with a blank value but is not required to be selected.
When the value is 'true', the picker object will start with a blank value and will not validate until a user has selected an option.
When the value is not defined, the picker behaves as normal.
Returns
Form
This Form
Events
submit
Emitted when the form is submitted. The form data is included with this event. The data is an object containing the same form data that would be retrieved with form.getData()
Methods
componentpropertyStringObject
A method for getting the component for a form property. If the property provided doesn't exist or does not have a component, this function will return undefined.
Arguments
propertyString
The form property to get the component for.
Returns
Object
The component for a property if one exists.
dataObject
Returns the data in the form as an object containing key/value pairs.
If no keys are provided in the options, the name of each field will be used as the key.
Returns
Object
The data currently filled out in the form. It will look something like this:
{
  'Field 1': 25,
  'Field 2': 'green',
  'Field 3': true,
  'Field 4': 'Two'
}
datadataObjectForm
Fill the form with some data.
Arguments
data
The values to fill the form with. The expected format of the data is a an object where the keys match the labels, and the values are the values to set the input to:
{
  'Field 1': 25,
  'Field 2': 'green',
  'Field 3': true,
  'Field 4': 'Two'
}
Returns
Form
This Form
disabledpropertiesArray[String]disabledBooleanForm
A method for setting the disabled state for an array of properties in a form.
Arguments
propertiesArray[String]
The array of properties/keys to use.
disabledBoolean
Returns
Form
The current form
disabledpropertyStringdisabledBooleanForm
A method for setting the disabled state for a property in a form.
Arguments
propertyString
The property/key to use.
disabledBoolean
Returns
Form
The current form
disabledpropertiesArray[String]Array[Boolean]
A method for getting the disabled state for an array of properties in a form.
Arguments
propertiesArray[String]
The array of properties/keys to use.
Returns
An array indicating the disabled state of each property in the array of properties. If a property does not exist, it's value will be undefined.
disabledpropertyStringBoolean
A method for getting the disabled state of a property in a form.
Arguments
propertyString
The property/key to use.
Returns
The disabled state of the property. If the property does not exist, returns undefined.
errorMessagepropertyStringmessageStringForm
A method for setting custom error messages for form fields. If the message is set to anything other than an empty string, the form input will be classed as invalid and show a validation message.
form.errorMessage('Text', 'Please enter something sensible') // Form will not validate with message 'Please enter something sensible'
form.errorMessage('Text', undefined) // Clears validation message.
Arguments
propertyString
The property/key to use.
messageString
The message to set.
Returns
Form
This Form
errorMessagepropertyStringString
A method for getting the error message for a form field. This will include messages set with the errorMessage method as well as inbuilt errors, such as those shown for required fields.
Arguments
propertyString
The property/key to use.
Returns
The error message for the property.
hiddenpropertiesArray[String]hiddenBooleanForm
A method setting the hidden state for a set of form properties. Hidden properties will be visually hidden and their values will not be present in the form data.
Arguments
propertiesArray[String]
The array of properties/keys to use.
hiddenBoolean
Whether each property is hidden.
Returns
Form
This Form
hiddenpropertyStringBoolean
A method getting the hidden state for a form property. Hidden properties will be visually hidden and their values will not be present in the form data.
Arguments
propertyString
The property/key to use.
Returns
Whether the property is hidden.
hiddenpropertyStringhiddenBooleanForm
A method setting the hidden state for a form property. Hidden properties will be visually hidden and their values will not be present in the form data.
Arguments
propertyString
The property/key to use.
hiddenBoolean
Whether the property is hidden.
Returns
Form
This Form
hiddenpropertiesArray[String]Array[Boolean]
A method getting the hidden state for a set of form properties. Hidden properties will be visually hidden and their values will not be present in the form data.
Arguments
propertiesArray[String]
The array of properties/keys to use.
Returns
Whether each property is hidden.
nodepropertyStringHTMLElement
A method for getting the node for a form property
Arguments
propertyString
The property/key to use.
Returns
HTMLElement
The selected node
submitForm
Force the form to emit a 'submit' event.
Returns
Form
This Form
valuepropertyStringvalueAnyForm
A method for setting the value for a single property in a form.
Arguments
propertyString
The property/key to use.
valueAny
The value to set.
Returns
Form
This Form
valuepropertyStringAny
A method for getting the value for a single property in a form.
Arguments
propertyString
The property/key to use.
Returns
Any
The property value.