Improve this Doc View Source form.FormController

Methods

• $rollbackViewValue();

  Rollback all form controls pending updates to the $modelValue.

  Updates may be pending by a debounced event or because the input is waiting for a some future event defined in ng-model-options. This method is typically needed by the reset button of a form that uses ng-model-options to pend updates.

• $commitViewValue();

  Commit all form controls pending updates to the $modelValue.

  Updates may be pending by a debounced event or because the input is waiting for a some future event defined in ng-model-options. This method is rarely needed as NgModelController usually handles calling this in response to input events.

• $addControl(control);

  Register a control with the form. Input elements using ngModelController do this automatically when they are linked.

  Note that the current state of the control will not be reflected on the new parent form. This is not an issue with normal use, as freshly compiled and linked controls are in a $pristine state.

  However, if the method is used programmatically, for example by adding dynamically created controls, or controls that have been previously removed without destroying their corresponding DOM element, it's the developers responsibility to make sure the current state propagates to the parent form.

  For example, if an input control is added that is already $dirty and has $error properties, calling $setDirty() and $validate() afterwards will propagate the state to the parent form.

  Parameters

  Param	Type	Details
  control	object	control object, either a form.FormController or an ngModel.NgModelController

• $getControls();

  This method returns a shallow copy of the controls that are currently part of this form. The controls can be instances of FormController ("child-forms") and of NgModelController. If you need access to the controls of child-forms, you have to call $getControls() recursively on them. This can be used for example to iterate over all controls to validate them.

  The controls can be accessed normally, but adding to, or removing controls from the array has no effect on the form. Instead, use $addControl() and $removeControl() for this use-case. Likewise, adding a control to, or removing a control from the form is not reflected in the shallow copy. That means you should get a fresh copy from $getControls() every time you need access to the controls.

  Returns

  Array

  the controls that are currently part of this form

• $removeControl(control);

  Deregister a control from the form.

  Input elements using ngModelController do this automatically when they are destroyed.

  Note that only the removed control's validation state ($errorsetc.) will be removed from the form. $dirty, $submitted states will not be changed, because the expected behavior can be different from case to case. For example, removing the only $dirty control from a form may or may not mean that the form is still $dirty.

  Parameters

  Param	Type	Details
  control	object	control object, either a form.FormController or an ngModel.NgModelController

• $setDirty();

  Sets the form to a dirty state.

  This method can be called to add the 'ng-dirty' class and set the form to a dirty state (ng-dirty class). This method will also propagate to parent forms.

• $setPristine();

  Sets the form to its pristine state.

  This method sets the form's $pristine state to true, the $dirty state to false, removes the ng-dirty class and adds the ng-pristine class. Additionally, it sets the $submitted state to false.

  This method will also propagate to all the controls contained in this form.

  Setting a form back to a pristine state is often useful when we want to 'reuse' a form after saving or resetting it.

• $setUntouched();

  Sets the form to its untouched state.

  This method can be called to remove the 'ng-touched' class and set the form controls to their untouched state (ng-untouched class).

  Setting a form controls back to their untouched state is often useful when setting the form back to its pristine state.

• $setSubmitted();

  Sets the form to its $submitted state. This will also set $submitted on all child and parent forms of the form.

• $setValidity(validationErrorKey, isValid, controller);

  Change the validity state of the form, and notify the parent form (if any).

  Application developers will rarely need to call this method directly. It is used internally, by NgModelController.$setValidity(), to propagate a control's validity state to the parent FormController.

  Parameters

  Param	Type	Details
  validationErrorKey	string	Name of the validator. The validationErrorKey will be assigned to either $error[validationErrorKey] or $pending[validationErrorKey] (for unfulfilled $asyncValidators), so that it is available for data-binding. The validationErrorKey should be in camelCase and will get converted into dash-case for class name. Example: myError will result in ng-valid-my-error and ng-invalid-my-error classes and can be bound to as {{ someForm.$error.myError }}.
  isValid	boolean	Whether the current state is valid (true), invalid (false), pending (undefined), or skipped (null). Pending is used for unfulfilled $asyncValidators. Skipped is used by AngularJS when validators do not run because of parse errors and when $asyncValidators do not run because any of the $validators failed.
  controller	NgModelControllerFormController	The controller whose validity state is triggering the change.

Properties

• $pristine

  boolean

  True if user has not interacted with the form yet.

• $dirty

  boolean

  True if user has already interacted with the form.

• $valid

  boolean

  True if all of the containing forms and controls are valid.

• $invalid

  boolean

  True if at least one containing control or form is invalid.

• $submitted

  boolean

  True if user has submitted the form even if its invalid.

• $pending

  Object

  An object hash, containing references to controls or forms with pending validators, where: keys are validations tokens (error names). values are arrays of controls or forms that have a pending validator for the given error name. See $error for a list of built-in validation tokens.

• $error

  Object

  An object hash, containing references to controls or forms with failing validators, where: keys are validation tokens (error names), values are arrays of controls or forms that have a failing validator for the given error name. Built-in validation tokens: email max maxlength min minlength number pattern required url date datetimelocal time week month