Components.FormElement Class
Sub class of Components.FormGroup that adds automatic form layout markup and form validation features.
Form layout
The appropriate Bootstrap markup for the given formLayout and controlType is automatically generated to easily
create forms without coding the default Bootstrap form markup by hand:
{{#bs-form formLayout="horizontal" action="submit"}}
{{bs-form-element controlType="email" label="Email" placeholder="Email" value=email}}
{{bs-form-element controlType="password" label="Password" placeholder="Password" value=password}}
{{bs-form-element controlType="checkbox" label="Remember me" value=rememberMe}}
{{bs-button defaultText="Submit" type="primary" buttonType="submit"}}
{{/bs-form}}
Form validation
In the following example the control elements of the three form elements value will be bound to the properties
(given by property) of the form's model, which in this case is its controller (see model=this):
{{#bs-form formLayout="horizontal" model=this action="submit"}}
{{bs-form-element controlType="email" label="Email" placeholder="Email" property="email"}}
{{bs-form-element controlType="password" label="Password" placeholder="Password" property="password"}}
{{bs-form-element controlType="checkbox" label="Remember me" property="rememberMe"}}
{{bs-button defaultText="Submit" type="primary" buttonType="submit"}}
{{/bs-form}}
By using this indirection in comparison to directly binding the value property, you get the benefit of automatic
form validation, given that your model has a supported means of validating itself.
See Components.Form for details on how to enable form validation.
In the example above the model was our controller itself, so the control elements were bound to the appropriate
properties of our controller. A controller implementing validations on those properties could look like this:
import Ember from 'ember';
import EmberValidations from 'ember-validations';
export default Ember.Controller.extend(EmberValidations,{
email: null,
password: null,
rememberMe: false,
validations: {
email: {
presence: true,
format: {
with: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$/
}
},
password: {
presence: true,
length: { minimum: 6, maximum: 10}
},
comments: {
length: { minimum: 5, maximum: 20}
}
}
});
If the showValidation property is true (which is automatically the case if a focusOut event is captured from the
control element or the containing Components.Form was submitted with its model failing validation) and there are
validation errors for the model's property, the appropriate Bootstrap validation markup (see
http://getbootstrap.com/css/#forms-control-validation) is applied:
validationis set to 'error', which will set thehas-errorCSS class- the
errorIconfeedback icon is displayed ifcontrolTypeis a text field - the validation messages are displayed as Bootstrap
help-blocks
The same applies for warning messages, if the used validation library supports this. (Currently only ember-cp-validations)
As soon as the validation is successful again...
validationis set to 'success', which will set thehas-successCSS class- the
successIconfeedback icon is displayed ifcontrolTypeis a text field - the validation messages are removed
Custom controls
Apart from the standard built-in browser controls (see the controlType property), you can use any custom control simply
by invoking the component with a block template. Use whatever control you might want, for example a select-2 component
(from the ember-select-2 addon):
{{#bs-form formLayout="horizontal" model=this action="submit"}}
{{#bs-form-element label="Select-2" property="gender" useIcons=false as |value id validationState|}}
{{select-2 id=id content=genderChoices optionLabelPath="label" value=value searchEnabled=false}}
{{/bs-form-element}}
{{/bs-form}}
If your custom control does not render an input element, you should set useIcons to false since bootstrap only supports
feedback icons with textual <input class="form-control"> elements.
Item Index
Properties
- _showValidationOn
- autofocus
- choiceLabelProperty
- choices
- choiceValueProperty
- cols
- controlType
- disabled
- errorIcon
- errors
- errors
- form
- formElementId
- formLayout
- hasErrors
- hasFeedback
- hasLabel
- hasValidation
- hasValidationMessages
- hasValidator
- hasWarnings
- horizontalInputGridClass
- horizontalInputOffsetGridClass
- horizontalLabelGridClass
- infoIcon
- invisibleLabel
- isHorizontal
- isInline
- isValidating
- isVertical
- label
- model
- name
- placeholder
- property
- readonly
- required
- rows
- showErrors deprecated
- showValidation
- showValidationMessages
- showValidationOn
- successIcon
- useIcons
- validation
- validationMessages
- value
- warningIcon
Methods
setupValidations
protectedSetup validation properties. This method acts as a hook for external validation
libraries to overwrite. In case of failed validations the errors property should contain an array of error messages.
showValidationOnHandler
privateProperties
_showValidationOn array
privateautofocus boolean
publicControl element's HTML5 autofocus attribute
choiceLabelProperty string
publicThe property of the choices array of objects, containing the label of the choice, e.g. the select box option.
choices array
publicAn array of objects containing the selection of choices for multiple choice style form controls, e.g. select boxes.
{{bs-form-element controlType="select" choices=countries choiceLabelProperty="name" choiceValueProperty="id" label="Country" value=selectedCountry}}
Be sure to also set the choiceValueProperty and choiceLabelProperty properties.
choiceValueProperty string
publicThe property of the choices array of objects, containing the value of the choice, e.g. the select box option.
cols number
publicTextarea's cols attribute (ignored for other controlTypes)
controlType string
publicThe type of the control widget. Supported types:
- 'text'
- 'checkbox'
- 'select' (deprecated)
- 'textarea'
- any other type will use an input tag with the
controlTypevalue as the type attribute (for e.g. HTML5 input types like 'email'), and the same layout as the 'text' type
disabled boolean
publicControl element's HTML5 disabled attribute
errorIcon string
publicuseIcons is false.
You can change this globally by setting the formValidationErrorIcon property of
the ember-bootstrap configuration in your config/environment.js file. If your are
using FontAwesome for example:
`js
ENV['ember-bootstrap'] = {
formValidationErrorIcon: 'fa fa-times'
}
`
errors array
protectedThe array of warning messages from the model's validation.
errors array
protectedThe array of error messages from the model's validation.
form unknown
protectedReference to the parent Components.Form class.
formElementId string
privateID for input field and the corresponding label's "for" attribute
formLayout string
publicThe form layout used for the markup generation (see http://getbootstrap.com/css/#forms):
- 'horizontal'
- 'vertical'
- 'inline'
Defaults to the parent form's formLayout property.
hasErrors boolean
protectedhasFeedback boolean
publichasLabel boolean
protectedhasValidation boolean
publichasValidationMessages boolean
protectedhasValidator boolean
protectedhasWarnings boolean
protectedhorizontalInputGridClass string
protectedComputed property that specifies the Bootstrap grid class for form controls within a horizontal layout form.
horizontalInputOffsetGridClass string
protectedComputed property that specifies the Bootstrap offset grid class for form controls within a horizontal layout form, that have no label.
horizontalLabelGridClass string
publicThe Bootstrap grid class for form labels within a horizontal layout form. Defaults to the value of the same property of the parent form. The corresponding grid class for form controls is automatically computed.
Default: 'col-md-4'
infoIcon string
publicuseIcons is false.
You can change this globally by setting the formValidationInfoIcon property of
the ember-bootstrap configuration in your config/environment.js file. If your are
using FontAwesome for example:
`js
ENV['ember-bootstrap'] = {
formValidationInfoIcon: 'fa fa-info-circle
}
`
The "info" validation state is not supported in Bootstrap CSS, but can be easily added
using the following LESS style:
`less
.has-info {
.form-control-validation(@state-info-text; @state-info-text; @state-info-bg);
}
`
invisibleLabel boolean
publicControls label visibilty by adding 'sr-only' class.
isHorizontal boolean
protectedisInline boolean
protectedisValidating boolean
publicSet a validating state for async validations
Default: false
isVertical boolean
protectedlabel string
publicText to display within a <label> tag.
You should include a label for every form input cause otherwise screen readers
will have trouble with your forms. Use invisibleLabel property if you want
to hide them.
model unknown
publicThe model used for validation. Defaults to the parent Components.Form's model
name string
publicControl element's name attribute
placeholder string
publicControl element's HTML5 placeholder attribute
property string
publicThe property name of the form element's model (by default the model of its parent Components.Form) that this
form element should represent. The control element's value will automatically be bound to the model property's
value.
Using this property enables form validation on this element.
readonly boolean
publicControl element's HTML5 readonly attribute
required boolean
publicControl element's HTML5 required attribute
rows number
publicTextarea's rows attribute (ignored for other controlTypes)
Default: 5
showErrors boolean
deprecated protectedshowValidation boolean
publicIf true form validation markup is rendered (requires a validatable model).
Default: false
showValidationMessages boolean
protectedshowValidationOn string|array
publicEvent or list of events which enable form validation markup rendering. Supported events: ['focusOut', 'change']
Default: ['focusOut']
successIcon string
publicuseIcons is false.
You can change this globally by setting the formValidationSuccessIcon property of
the ember-bootstrap configuration in your config/environment.js file. If your are
using FontAwesome for example:
`js
ENV['ember-bootstrap'] = {
formValidationSuccessIcon: 'fa fa-check'
}
`
Default: 'glyphicon glyphicon-ok'
useIcons boolean
publicTrue for text field controlTypes
validation string
protectedThe validation ("error" or "success") or null if no validation is to be shown. Automatically computed from the models validation state.
validationMessages array
protectedThe array of validation messages (either errors or warnings) rom the model's validation.
value unknown
publicThe value of the control element is bound to this property. You can bind it to some controller property to get/set the control element's value:
{{bs-form-element controlType="email" label="Email" placeholder="Email" value=email}}
Note: you loose the ability to validate this form element by directly binding to its value. It is recommended
to use the property feature instead.
warningIcon string
publicuseIcons is false.
You can change this globally by setting the formValidationWarningIcon property of
the ember-bootstrap configuration in your config/environment.js file. If your are
using FontAwesome for example:
`js
ENV['ember-bootstrap'] = {
formValidationWarningIcon: 'fa fa-warning'
}
`
Events
change
private
Listen for change events from the control element to automatically set showValidation to true to enable
form validation markup rendering if showValidationsOn contains change.
focusOut
private
Listen for focusOut events from the control element to automatically set showValidation to true to enable
form validation markup rendering if showValidationsOn contains focusOut.