Skip to content

Commit d7a78e4

Browse files
committed
docs(select): add more notes about ngRepeat and clean up style
Closes angular#9592
1 parent 4b4098b commit d7a78e4

File tree

1 file changed

+18
-15
lines changed

1 file changed

+18
-15
lines changed

src/ng/directive/select.js

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -15,34 +15,37 @@ var ngOptionsMinErr = minErr('ngOptions');
1515
* elements for the `<select>` element using the array or object obtained by evaluating the
1616
* `ngOptions` comprehension_expression.
1717
*
18+
* In many cases, `ngRepeat` can be used on `<option>` elements instead of `ngOptions` to achieve a
19+
* similar result. However, the `ngOptions` provides some benefits such as reducing memory and
20+
* increasing speed by not creating a new scope for each repeated instance, as well as providing
21+
* more flexibility in how the `select`'s model is assigned via `select as`. `ngOptions should be
22+
* used when the `select` model needs to be bound to a non-string value. This is because an option
23+
* element can only be bound to string values at present.
24+
*
1825
* When an item in the `<select>` menu is selected, the array element or object property
1926
* represented by the selected option will be bound to the model identified by the `ngModel`
2027
* directive.
2128
*
22-
* <div class="alert alert-warning">
23-
* **Note:** `ngModel` compares by reference, not value. This is important when binding to an
24-
* array of objects. See an example [in this jsfiddle](http://jsfiddle.net/qWzTb/).
25-
* </div>
26-
*
2729
* Optionally, a single hard-coded `<option>` element, with the value set to an empty string, can
2830
* be nested into the `<select>` element. This element will then represent the `null` or "not selected"
2931
* option. See example below for demonstration.
3032
*
3133
* <div class="alert alert-warning">
32-
* **Note:** `ngOptions` provides an iterator facility for the `<option>` element which should be used instead
33-
* of {@link ng.directive:ngRepeat ngRepeat} when you want the
34-
* `select` model to be bound to a non-string value. This is because an option element can only
35-
* be bound to string values at present.
34+
* **Note:** `ngModel` compares by reference, not value. This is important when binding to an
35+
* array of objects. See an example [in this jsfiddle](http://jsfiddle.net/qWzTb/).
3636
* </div>
3737
*
38-
* <div class="alert alert-info">
39-
* **Note:** Using `select as` will bind the result of the `select as` expression to the model, but
38+
* ## `select as`
39+
*
40+
* Using `select as` will bind the result of the `select as` expression to the model, but
4041
* the value of the `<select>` and `<option>` html elements will be either the index (for array data sources)
41-
* or property name (for object data sources) of the value within the collection.
42-
* </div>
42+
* or property name (for object data sources) of the value within the collection. If a `track by` expression
43+
* is used, the result of that expression will be set as the value of the `option` and `select` elements.
44+
*
45+
* ### `select as` with `trackexpr`
46+
*
47+
* Using `select as` together with `trackexpr` is not recommended. Reasoning:
4348
*
44-
* **Note:** Using `select as` together with `trackexpr` is not recommended.
45-
* Reasoning:
4649
* - Example: &lt;select ng-options="item.subItem as item.label for item in values track by item.id" ng-model="selected"&gt;
4750
* values: [{id: 1, label: 'aLabel', subItem: {name: 'aSubItem'}}, {id: 2, label: 'bLabel', subItem: {name: 'bSubItem'}}],
4851
* $scope.selected = {name: 'aSubItem'};

0 commit comments

Comments
 (0)