Improve this doc View Source

`NgModelController` provides API for the `ng-model` directive. The controller contains services for data-binding, validation, CSS updates, and value formatting and parsing. It purposefully does not contain any logic which deals with DOM rendering or listening to DOM events. Such DOM related logic should be provided by other directives which make use of `NgModelController` for data-binding.

## Custom Control Example

This example shows how to use `NgModelController` with a custom control to achieve data-binding. Notice how different directives (`contenteditable`, `ng-model`, and `required`) collaborate together to achieve the desired result.

Note that `contenteditable` is an HTML5 attribute, which tells the browser to let the element contents be edited in place by the user. This will not work on older browsers.

We are using the $sce service here and include the $sanitize module to automatically remove "bad" content like inline event listener (e.g. `<span onclick="...">`). However, as we are using `$sce` the model can still decide to to provide unsafe content if it marks that content using the `$sce` service.

Edit in Plunker

    [contenteditable] {
      border: 1px solid black;
      background-color: white;
      min-height: 20px;
    }

    .ng-invalid {
      border: 1px solid red;
    }

    angular.module('customControl', ['ngSanitize']).
      directive('contenteditable', ['$sce', function($sce) {
        return {
          restrict: 'A', // only activate on element attribute
          require: '?ngModel', // get a hold of NgModelController
          link: function(scope, element, attrs, ngModel) {
            if(!ngModel) return; // do nothing if no ng-model

            // Specify how UI should be updated
            ngModel.$render = function() {
              element.html($sce.getTrustedHtml(ngModel.$viewValue || ''));
            };

            // Listen for change events to enable binding
            element.on('blur keyup change', function() {
              scope.$apply(read);
            });
            read(); // initialize

            // Write data to the model
            function read() {
              var html = element.html();
              // When we clear the content editable the browser leaves a <br> behind
              // If strip-br attribute is provided then we strip this out
              if( attrs.stripBr && html == '<br>' ) {
                html = '';
              }
              ngModel.$setViewValue(html);
            }
          }
        };
      }]);

    <form name="myForm">
     <div contenteditable
          name="myWidget" ng-model="userContent"
          strip-br="true"
          required>Change me!</div>
      <span ng-show="myForm.myWidget.$error.required">Required!</span>
     <hr>
     <textarea ng-model="userContent"></textarea>
    </form>

    it('should data-bind and become invalid', function() {
    if (browser.params.browser == 'safari' || browser.params.browser == 'firefox') {
      // SafariDriver can't handle contenteditable
      // and Firefox driver can't clear contenteditables very well
      return;
    }
    var contentEditable = element(by.css('[contenteditable]'));
    var content = 'Change me!';

    expect(contentEditable.getText()).toEqual(content);

    contentEditable.clear();
    contentEditable.sendKeys(protractor.Key.BACK_SPACE);
    expect(contentEditable.getText()).toEqual('');
    expect(contentEditable.getAttribute('class')).toMatch(/ng-invalid-required/);
    });

## Methods

- ###

  `$render();`

  Called when the view needs to be updated. It is expected that the user of the ng-model directive will implement this method.

- ###

  `$isEmpty(value);`

  This is called when we need to determine if the value of the input is empty.

  For instance, the required directive does this to work out if the input has data or not. The default `$isEmpty` function checks whether the value is `undefined`, `''`, `null` or `NaN`.

  You can override this for input directives whose concept of being empty is different to the default. The `checkboxInputType` directive does this because in its case a value of `false` implies empty.

  #### Parameters

  Param | Type | Details
  --- | --- | ---
  value | * | Reference to check.

  #### Returns

  boolean | True if `value` is empty.

- ###

  `$setValidity(validationErrorKey, isValid);`

  Change the validity state, and notifies the form when the control changes validity. (i.e. it does not notify form if given validator is already marked as invalid).

  This method should be called by validators - i.e. the parser or formatter functions.

  #### Parameters

  Param | Type | Details
  --- | --- | ---
  validationErrorKey | string | Name of the validator. the `validationErrorKey` will assign to `$error[validationErrorKey]=isValid` 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` class and can be bound to as `{{someForm.someControl.$error.myError}}` .
  isValid | boolean | Whether the current state is valid (true) or invalid (false).

- ###

  `$setPristine();`

  Sets the control to its pristine state.

  This method can be called to remove the 'ng-dirty' class and set the control to its pristine state (ng-pristine class).

- ###

  `$rollbackViewValue();`

  Cancel an update and reset the input element's value to prevent an update to the `$modelValue`, which may be caused by a pending debounced event or because the input is waiting for a some future event.

  If you have an input that uses `ng-model-options` to set up debounced events or events such as blur you can have a situation where there is a period when the `$viewValue` is out of synch with the ngModel's `$modelValue`.

  In this case, you can run into difficulties if you try to update the ngModel's `$modelValue` programmatically before these debounced/future events have resolved/occurred, because Angular's dirty checking mechanism is not able to tell whether the model has actually changed or not.

  The `$rollbackViewValue()` method should be called before programmatically changing the model of an input which may have such events pending. This is important in order to make sure that the input field will be updated with the new model value and any pending operations are cancelled.

  Edit in Plunker

      angular.module('cancel-update-example', [])

      .controller('CancelUpdateCtrl', function($scope) {
        $scope.resetWithCancel = function (e) {
          if (e.keyCode == 27) {
            $scope.myForm.myInput1.$rollbackViewValue();
            $scope.myValue = '';
          }
        };
        $scope.resetWithoutCancel = function (e) {
          if (e.keyCode == 27) {
            $scope.myValue = '';
          }
        };
      });

      <div ng-controller="CancelUpdateCtrl">
        <p>Try typing something in each input.  See that the model only updates when you
           blur off the input.
         </p>
         <p>Now see what happens if you start typing then press the Escape key</p>

        <form name="myForm" ng-model-options="{ updateOn: 'blur' }">
          <p>With $rollbackViewValue()</p>
          <input name="myInput1" ng-model="myValue" ng-keydown="resetWithCancel($event)"><br/>
          myValue: "{{ myValue }}"

          <p>Without $rollbackViewValue()</p>
          <input name="myInput2" ng-model="myValue" ng-keydown="resetWithoutCancel($event)"><br/>
          myValue: "{{ myValue }}"
        </form>
      </div>

- ###

  `$commitViewValue();`

  Commit a pending update 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.

- ###

  `$setViewValue(value, trigger);`

  Update the view value.

  This method should be called when the view value changes, typically from within a DOM event handler. For example input and select directives call it.

  It will update the $viewValue, then pass this value through each of the functions in `$parsers`, which includes any validators. The value that comes out of this `$parsers` pipeline, be applied to `$modelValue` and the expression specified in the `ng-model` attribute.

  Lastly, all the registered change listeners, in the `$viewChangeListeners` list, are called.

  In case the ngModelOptions directive is used with `updateOn` and the `default` trigger is not listed, all those actions will remain pending until one of the `updateOn` events is triggered on the DOM element. All these actions will be debounced if the ngModelOptions directive is used with a custom debounce for this particular event.

  Note that calling this function does not trigger a `$digest`.

  #### Parameters

  Param | Type | Details
  --- | --- | ---
  value | string | Value from the view.
  trigger | string | Event that triggered the update.

## Properties

- ### `$viewValue`

  string | Actual string value in the view.

- ### `$modelValue`

  * | The value in the model, that the control is bound to.

- ### `$parsers`

  Array.<Function> | Array of functions to execute, as a pipeline, whenever the control reads value from the DOM. Each function is called, in turn, passing the value through to the next. The last return value is used to populate the model. Used to sanitize / convert the value as well as validation. For validation, the parsers should update the validity state using $setValidity(), and return `undefined` for invalid values.

- ### `$formatters`

  Array.<Function> | Array of functions to execute, as a pipeline, whenever the model value changes. Each function is called, in turn, passing the value through to the next. Used to format / convert values for display in the control and validation.
      function formatter(value) {
        if (value) {
          return value.toUpperCase();
        }
      }
      ngModel.$formatters.push(formatter);

- ### `$viewChangeListeners`

  Array.<Function> | Array of functions to execute whenever the view value has changed. It is called with no arguments, and its return value is ignored. This can be used in place of additional $watches against the model value.

- ### `$error`

  Object | An object hash with all errors as keys.

- ### `$pristine`

  boolean | True if user has not interacted with the control yet.

- ### `$dirty`

  boolean | True if user has already interacted with the control.

- ### `$valid`

  boolean | True if there is no error.

- ### `$invalid`

  boolean | True if at least one error on the control.