👍

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

options

Options for the form. The formState property is passed to all formly-fields and is a mechanism for communicating between fields (without having to mess with your model).

This also receives the methods resetModel and updateInitialValue which will invoke all of the field's resetModel and updateInitialValue respectively.

removeChromeAutoComplete: Chrome purposefully broke autocomplete="off" which really really stinks. Specify this option as true to fix this and remove the browser's ugly autocomplete from your form. You can also configure this globally using formlyConfig. Uses this hack

root-el

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.

template (string)

template can be set instead of type or templateUrl to use a custom html template form field. Should be used with one-liners mostly (like a directive), or if you're using webpack with the ability to require templates :-)

📘

Add Normal HTML

This can be used to add HTML instead of a form field.

vm.fields = [
  {
    noFormControl: true,
    template: '<p>Some text here</p>'
  },
  // templateUrl works too
  {
    noFormControl: true,
    templateUrl: 'path/to/template.html'
  }
];

See below for an explanation on why noFormControl is needed.

templateUrl (string)

templateUrl can be set instead of type or template to use a custom html template form field. Works just like a directive templateUrl and uses the $templateCache

key (string)

By default form models are keyed by location in the form array, you can override this by specifying a key.

vm.model = {};
vm.fields = [
  {
    // this field's ng-model will be bound to vm.model.username
    key: 'username',
    type: 'input'
  }
];

<formly-form model="vm.model" fields="vm.fields"></formly-form>

hide (boolean)

Whether to hide the field (uses ng-if). Defaults to false. If you wish this to be conditional, use expressionProperties. See below.

model (object)

By default, the model passed to the formly-field directive is the same as the model passed to the formly-form. However, if the field has a model specified, then the specified model is used for that field (and that field only). In addition, a deep watch is added to the formly-field directive's scope to run the expressionProperties 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 using formlyEval from formlyUtils see below for more information. The returned value is wrapped in $q.when so you can return a promise from your function :-)

NG-NL Talk Excerpt

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 (object)

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 (object)

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 to setWrapper in formlyConfig. It is expected to be the name of the wrapper specified there. The formly field template 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. For more information, see the guide on ngModelAttrs.

controller (controller name as string || controller function)

controller is a great way to add custom behavior to a specific field. 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 (index 1 will override index 0 properties). Also, these are applied after the type's defaultOptions and hence will override any duplicates of those properties as well.

modelOptions (object)

modelOptions allows you to take advantage of ng-model-options directive. Formly's built-in templateManipulator (see below) will add this attribute to your ng-model element automatically if this property exists. Note, if you use the getter/setter option, formly's templateManipulator will change the value of ng-model to options.value which is a getterSetter that formly adds to field options. For more information on ng-model-options, see this ng-conf talk and these egghead lessons.

noFormControl (boolean)

noFormControl is used to tell angular-formly to not attempt to add the formControl property to your object. This is useful for things like validation, but not necessary if your "field" doesn't use ng-model (if it's just a horizontal line for example). Defaults to false.

watcher (object|array of watches)

watcher is an object which has at least two properties called expression and listener. The watch.expression is added to the formly-form directive's scope (to allow it to run even when hide is true). You can specify a type ($watchCollection or $watchGroup) via the watcher.type property (defaults to $watch) and whether you want it to be a deep watch via the watcher.deep property (defaults to false).

🚧

Not a normal watch

This differs slightly from a normal $watch function in very useful ways. See Formly Expressions for more information.

validators (object)

validators is an object where the keys are the name of the validator and the values are Formly Expressions

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 :-)

📘

Validator as an object

You can alternatively specify a validator as an object with an expression and a message. This will unify how templates reference messages for when the validator has failed. Also, this should be used only for one-off messages (use ng-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. The formly-custom-validation directive will then add an object to the field options called validation.messages 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. This is especially useful when using ng-messages.

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 Formly Expressions mapped to message names. This is really useful when you're using ng-messages like in this example.

validation.show is a boolean you as the developer can set to specify to force options.validation.errorExistsAndShouldBeVisible (shortcut is showError) 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. See this example

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 :-)

📘

fc

For template authors, a shortcut is provided on the $scope for this property called fc

initialValue

This is used in combination with resetModel and updateInitialValue. Basically, this is set to the value this field represents at compile time, or the last time updateInitialValue is called.

resetModel

Will reset the field's model and the field control to the last initialValue.

updateInitialValue

Will reset the field's initialValue to the current state of the model. Useful if you load the model asynchronously. Invoke this when the model get set.

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 ngModelAttrsTemplateManipulator that comes built-in with formly, it will automagically change your field's ng-model attribute to use options.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.

validation.errorExistsAndShouldBeVisible

This is 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).

📘

showError

For template authors, a shortcut is provided on the $scope for this property called showError