Skip to content

Commit 89a8bf7

Browse files
committed
docs(input): clarify input and ngModel behavior
1 parent 0692c80 commit 89a8bf7

File tree

1 file changed

+34
-12
lines changed

1 file changed

+34
-12
lines changed

src/ng/directive/input.js

+34-12
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@ var inputType = {
3131
* @description
3232
* Standard HTML text input with angular data binding, inherited by most of the `input` elements.
3333
*
34-
* *NOTE* Not every feature offered is available for all input types.
3534
*
3635
* @param {string} ngModel Assignable angular expression to data-bind to.
3736
* @param {string=} name Property name of the form under which the control is published.
@@ -115,7 +114,10 @@ var inputType = {
115114
* the HTML5 date input, a text element will be used. In that case, text must be entered in a valid ISO-8601
116115
* date format (yyyy-MM-dd), for example: `2009-01-06`. Since many
117116
* modern browsers do not yet support this input type, it is important to provide cues to users on the
118-
* expected input format via a placeholder or label. The model must always be a Date object.
117+
* expected input format via a placeholder or label.
118+
*
119+
* The model must always be a Date object, otherwise Angular will throw an error.
120+
* Invalid `Date` objects (dates whose `getTime()` is `NaN`) will be rendered as an empty string.
119121
*
120122
* The timezone to be used to read/write the `Date` instance in the model can be defined using
121123
* {@link ng.directive:ngModelOptions ngModelOptions}. By default, this is the timezone of the browser.
@@ -203,7 +205,10 @@ var inputType = {
203205
* @description
204206
* Input with datetime validation and transformation. In browsers that do not yet support
205207
* the HTML5 date input, a text element will be used. In that case, the text must be entered in a valid ISO-8601
206-
* local datetime format (yyyy-MM-ddTHH:mm:ss), for example: `2010-12-28T14:57:00`. The model must be a Date object.
208+
* local datetime format (yyyy-MM-ddTHH:mm:ss), for example: `2010-12-28T14:57:00`.
209+
*
210+
* The model must always be a Date object, otherwise Angular will throw an error.
211+
* Invalid `Date` objects (dates whose `getTime()` is `NaN`) will be rendered as an empty string.
207212
*
208213
* The timezone to be used to read/write the `Date` instance in the model can be defined using
209214
* {@link ng.directive:ngModelOptions ngModelOptions}. By default, this is the timezone of the browser.
@@ -294,6 +299,9 @@ var inputType = {
294299
* local time format (HH:mm:ss), for example: `14:57:00`. Model must be a Date object. This binding will always output a
295300
* Date object to the model of January 1, 1970, or local date `new Date(1970, 0, 1, HH, mm, ss)`.
296301
*
302+
* The model must always be a Date object, otherwise Angular will throw an error.
303+
* Invalid `Date` objects (dates whose `getTime()` is `NaN`) will be rendered as an empty string.
304+
*
297305
* The timezone to be used to read/write the `Date` instance in the model can be defined using
298306
* {@link ng.directive:ngModelOptions ngModelOptions}. By default, this is the timezone of the browser.
299307
*
@@ -380,7 +388,10 @@ var inputType = {
380388
* @description
381389
* Input with week-of-the-year validation and transformation to Date. In browsers that do not yet support
382390
* the HTML5 week input, a text element will be used. In that case, the text must be entered in a valid ISO-8601
383-
* week format (yyyy-W##), for example: `2013-W02`. The model must always be a Date object.
391+
* week format (yyyy-W##), for example: `2013-W02`.
392+
*
393+
* The model must always be a Date object, otherwise Angular will throw an error.
394+
* Invalid `Date` objects (dates whose `getTime()` is `NaN`) will be rendered as an empty string.
384395
*
385396
* The timezone to be used to read/write the `Date` instance in the model can be defined using
386397
* {@link ng.directive:ngModelOptions ngModelOptions}. By default, this is the timezone of the browser.
@@ -466,8 +477,11 @@ var inputType = {
466477
* @description
467478
* Input with month validation and transformation. In browsers that do not yet support
468479
* the HTML5 month input, a text element will be used. In that case, the text must be entered in a valid ISO-8601
469-
* month format (yyyy-MM), for example: `2009-01`. The model must always be a Date object. In the event the model is
470-
* not set to the first of the month, the first of that model's month is assumed.
480+
* month format (yyyy-MM), for example: `2009-01`.
481+
*
482+
* The model must always be a Date object, otherwise Angular will throw an error.
483+
* Invalid `Date` objects (dates whose `getTime()` is `NaN`) will be rendered as an empty string.
484+
* In the event that the model is not set to the first of the month, the first of that model's month is assumed.
471485
*
472486
* The timezone to be used to read/write the `Date` instance in the model can be defined using
473487
* {@link ng.directive:ngModelOptions ngModelOptions}. By default, this is the timezone of the browser.
@@ -556,6 +570,8 @@ var inputType = {
556570
* Text input with number validation and transformation. Sets the `number` validation
557571
* error if not a valid number.
558572
*
573+
* The model must always be a number, otherwise Angular will throw an error.
574+
*
559575
* @param {string} ngModel Assignable angular expression to data-bind to.
560576
* @param {string=} name Property name of the form under which the control is published.
561577
* @param {string=} min Sets the `min` validation error key if the value entered is less than `min`.
@@ -1351,10 +1367,14 @@ function checkboxInputType(scope, element, attr, ctrl, $sniffer, $browser, $filt
13511367
* @restrict E
13521368
*
13531369
* @description
1354-
* HTML input element control with angular data-binding. Input control follows HTML5 input types
1355-
* and polyfills the HTML5 validation behavior for older browsers.
1370+
* HTML input element control. When used together with {@link ngModel `ngModel`}, it provides data-binding,
1371+
* input state control, and validation.
1372+
* Input control follows HTML5 input types and polyfills the HTML5 validation behavior for older browsers.
13561373
*
1357-
* *NOTE* Not every feature offered is available for all input types.
1374+
* <div class="alert alert-warning">
1375+
* **Note:** Not every feature offered is available for all input types.
1376+
* Specifically, data binding and event handling via `ng-model` is unsupported for `input[file]`.
1377+
* </div>
13581378
*
13591379
* @param {string} ngModel Assignable angular expression to data-bind to.
13601380
* @param {string=} name Property name of the form under which the control is published.
@@ -1534,8 +1554,9 @@ var VALID_CLASS = 'ng-valid',
15341554
* is expected to return a promise when it is run during the model validation process. Once the promise
15351555
* is delivered then the validation status will be set to true when fulfilled and false when rejected.
15361556
* When the asynchronous validators are triggered, each of the validators will run in parallel and the model
1537-
* value will only be updated once all validators have been fulfilled. Also, keep in mind that all
1538-
* asynchronous validators will only run once all synchronous validators have passed.
1557+
* value will only be updated once all validators have been fulfilled. As long as an asynchronous validator
1558+
* is unfulfilled, its key will be added to the controllers `$pending` property. Also, all asynchronous validators
1559+
* will only run once all synchronous validators have passed.
15391560
*
15401561
* Please note that if $http is used then it is important that the server returns a success HTTP response code
15411562
* in order to fulfill the validation and a status level of `4xx` in order to reject the validation.
@@ -1791,7 +1812,8 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
17911812
* for class name. Example: `myError` will result in `ng-valid-my-error` and `ng-invalid-my-error`
17921813
* class and can be bound to as `{{someForm.someControl.$error.myError}}` .
17931814
* @param {boolean} isValid Whether the current state is valid (true), invalid (false), pending (undefined),
1794-
* or skipped (null).
1815+
* or skipped (null). Pending is used for unfulfilled `$asyncValidators` and skipped
1816+
* is for all validators that do not run because of parse errors.
17951817
*/
17961818
addSetValidityMethod({
17971819
ctrl: this,

0 commit comments

Comments
 (0)