Improve this Doc View Source ngModel.NgModelController

  1. type in module ng

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.

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 provide unsafe content if it marks that content using the $sce service.

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

  • $setViewValue(value);

    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.

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

    Parameters

    Param Type Details
    value string

    Value from the view.

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.

© 2010–2017 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://code.angularjs.org/1.2.32/docs/api/ng/type/ngModel.NgModelController