formly-form
directive
Wrap Dependencies
I highly recommend that you wrap almost all of your important dependencies in your own abstractions (not only angular-formly). This makes it very easy to upgrade if there's an ever a breaking change with your dependency. angular-formly is no exception to this. I recommend that you create your own directive that uses the
formly-form
directive and use that throughout your app.
Everything starts with the formly-form
. General use of it will look something like this:
<formly-form model="vm.myModel" fields="vm.myFields" form="vm.myForm">
<button type="submit" ng-disabled="vm.myForm.$invalid">Submit</button>
</formly-form>
Attributes
Attribute | Scope Type | Description |
---|---|---|
model | = binding (required) | The model to be represented by the form. |
fields | = binding (required) | The field configurations for building the form. See below for the configuration information. |
form | =? binding (optional) | The variable to bind the NgFormController to. |
options | =? binding (optional) | Options for the form. Currently only the formState property is used. It is passed to all formly-field s and is a mechanism for communicating between fields (without having to mess with your model ). |
root-el | N/A | You will not likely use this often (unless you have to support IE8, which is why it's a good idea to make your own directive that uses formly-form ). The value given will control what is used for the formly-form's root element. It defaults to an ng-form , but if you want it to use a form or a div then you would specify root-el="form" or root-el="div" (respectively). If you choose anything except a form or ng-form , make sure to wrap it in your own ng-form or form and provide that with a name. Then pass that name to the form attribute so all the formControls of the fields will have somewhere to be added to. |
Field Config
When constructing fields use the options below to customize each field object. You must set at least a type
, template
, or templateUrl
. These attributes are mutually exclusive.
You can only specify these properties. Additional properties will result in an error. If you need custom properties, use templateOptions
or data
.
type (string)
type
is the type of field to be rendered. Either type, template, or templateUrl must be set.
template (string)
template
can be set instead oftype
ortemplateUrl
to use a custom html template form field. Should be used with
one-liners mostly (like a directive). Useful for adding functionality to fields.
Note: This can be used to add HTML instead of a form field.
Examples:
template: '<p>Some text here</p>'
template: '<hr />'
templateUrl (string)
templateUrl
can be set instead oftype
ortemplate
to use a custom html template form field. Set a path relative
to the root of the application. iedirectives/custom-field.html
key (string)
By default form models are keyed by location in the form array, you can override this by specifying a
key
.
hide (boolean)
Whether to hide the field (uses
ng-if
)
model (object)
By default, the
model
passed to theformly-field
directive is the same as themodel
passed to theformly-form
.
However, if the field has amodel
specified, then the specifiedmodel
is used for that field (and that field only).
Also, a deep watch is added to theformly-field
directive's scope to run theexpressionProperties
when the specified
model
changes.
expressionProperties (object)
expressionProperties
is an object where the key is a property to be set on the main field config (can be an angular expression) and the value is an expression used to assign that property. The expression can be a function or string expression and will be evaluated usingformlyEval
fromformlyUtils
see below for more information. The returned value is wrapped in$q.when
so you can return a promise from your function :-)
For example:
vm.fields = [
{
key: 'myThing',
type: 'someType',
expressionProperties: {
'templateOptions.label': '$viewValue', // this would make the label change to what the user has typed
// this would set that property on data to be whether or not model.myThing.length > 5
'data.someproperty.somethingdeeper.whateveryouwant': 'model.myThing.length > 5'
}
}
];
data (*)
data
is reserved for the developer. You have our guarantee to be able to use this and not worry about future versions
of formly overriding your usage and preventing you from upgrading :-)
templateOptions (*)
templateOptions
is reserved for the templates. Any template-specific options go in here. Look at your specific
template implementation to know the options required for this.
wrapper (string|array of strings)
wrapper
makes reference tosetWrapper
in the formlyConfigProvider. It is expected to be the name of the wrapper
specified there. The formly field will be wrapped by the first wrapper, then the second, then the third, etc.
ngModelAttrs (object)
ngModelAttrs
is used in an angular-formly created templateManipulator to automatically add attributes to the ng-model
element of field templates. You will likely not use this often. This object is a little complex, but extremely powerful.
It's best to explain this api via an example. See the bottom for the example of this api.
controller (controller name|controller function)
controller
is a great way to add custom behavior to a specific field. You can also set the controller to a type as
well. It is injectable with the $scope of the field, and anything else you have in your injector.
link (link function)
link
allows you to specify a link function. It is invoked after your template has finished compiling. You are passed
the normal arguments for a normal link function.
optionsTypes (string|array of strings)
optionsTypes
allows you to specify extra types to get options from. Duplicate options are overridden in later
priority (index1
will override index0
properties). Also, these are applied after thetype
'sdefaultOptions
and hence will override any duplicates of those properties as well.
modelOptions (object)
modelOptions
allows you to take advantage ofng-model-options
directive. Formly's built-in templateManipulator (see
below) will add this attribute to yourng-model
element automatically if this property exists. Note, if you use the
getter/setter
option, formly's templateManipulator will change the value ofng-model
tooptions.value
which is a
getterSetter that formly adds to field options. For more information on ng-model-options, see
these
egghead
lessons.
watcher (object|array of watches)
watcher
is an object which has at least two properties calledexpression
andlistener
. Thewatch.expression
is
added to theformly-form
directive's scope. If it's a function, it will be wrapped and called with the field as the
first argument, followed by the normal arguments for a watcher, followed the watcher'sstop
function. If it's not
defined, it will default to the value of the field. Thelistener
will also be wrapped and called with the field as the
first argument, followed by the normal arguments for a watch listener. You can also specify a type ($watchCollection
or$watchGroup
) via thetype
property (defaults to$watch
) and whether you want it to be a deep watch via the
deep
property (defaults tofalse
).
How the api differs from a normal $watch
:
// normal watcher
$scope.$watch(function expression(theScope) {}, function listener(newValue, oldValue, theScope) {});
// field watcher
$scope.$watch(function expression(field, theScope, stop) {}, function listener(field, newValue, oldValue, theScope, stop) {});
validators (object)
validators
is an object where the keys are the name of the validity (to be passed to$setValidity
) and the values
are functions or expressions which returns true if it is valid. Templates can pass this option to the
formly-custom-validation
directive which will add a parser (or validator, see note) to thengModel
controller of
the field. The validator can be a function or string expression and will be evaluated usingformlyEval
from
formlyUtils
see below for more information.
Async validation: All function validators can return true/false/Promise. A validator passes if it returns true or
a promise that is resolved. A validator fails if it returns false or a promise that is rejected.
1.2: Formly defaults to use the
$validators
api, which is only available in angular 1.3. If you are using 1.2,
then the$parsers
api is used which doesn't support async validation out of the box. However, formly will keep track
of the validations for you and ensure that the most recently resolved/rejected promise is what takes priority. Also,
while the validation is in flight, formly emulates the$pending
api of 1.3 for your use in 1.2 as well, so you can
safely use this and upgrade to 1.3 without worrying about the upgrade path for this api. You're welcome :-)
NOTE: You can alternatively specify a validator as an object with an
expression
and amessage
. This will
unify how templates reference messages for when the validator has failed. Also, this should be used only for one-off
messages (useng-messages-include
for generic messages).message
in this case should be an expression that is
evaluated in exactly the same way a validator is evaluated. Theformly-custom-validation
directive will then add an
object to the field options calledvalidationMessages
which is a map of functions where the key is the validation name
and the value is a to function which returns the evaluated message.
validation (object)
validation
is an object with a few useful properties mostly handy when used in combination with ng-messages
validation.messages
a map of functions mapped to message names. These messages come from the validators. Invoke
these and angular-formly will evaluate them usingformlyUtil.formlyEval
(which is how validators themselves are
evaluated.
validation.errorExistsAndShouldBeVisible
a boolean indicating whether an error message should be shown. Because you
generally only want to show error messages when the user has interacted with a specific field, this value is set to
true based on this rule:field invalid && (field touched || validation.show)
validation.show
is a boolean you as the developer can set to specify to forceerrorExistsAndShouldBeVisible
to be set to true when there are$errors
. This is useful when you're trying to call the user's attention to some
fields for some reason.
Added Properties
Formly will add a few properties to your field config for convenience in templates
formControl
This is the NgModelController for the field. It provides you with awesome stuff like $errors
:-)
value
This is a getter/setter function for the value that your field is representing. Useful when using getterSetter: true
in the modelOptions
(in fact, if you don't disable the templateManipulator that comes built-in with formly, it will automagically change your field's ng-model
attribute to use value
.
runExpressions
It is not likely that you'll ever want to invoke this function. It simply runs the expressionProperties
expressions. It is used internally and you shouldn't have to use it, but you can if you want to.
Updated less than a minute ago