docs(select): add more notes about ngRepeat and clean up style

Closes #9592
This commit is contained in:
Jeff Cross
2014-10-14 11:10:52 -07:00
parent 4b4098bfca
commit d7a78e420a

View File

@@ -15,34 +15,37 @@ var ngOptionsMinErr = minErr('ngOptions');
* elements for the `<select>` element using the array or object obtained by evaluating the
* `ngOptions` comprehension_expression.
*
* In many cases, `ngRepeat` can be used on `<option>` elements instead of `ngOptions` to achieve a
* similar result. However, the `ngOptions` provides some benefits such as reducing memory and
* increasing speed by not creating a new scope for each repeated instance, as well as providing
* more flexibility in how the `select`'s model is assigned via `select as`. `ngOptions should be
* used when the `select` model needs to be bound to a non-string value. This is because an option
* element can only be bound to string values at present.
*
* When an item in the `<select>` menu is selected, the array element or object property
* represented by the selected option will be bound to the model identified by the `ngModel`
* directive.
*
* <div class="alert alert-warning">
* **Note:** `ngModel` compares by reference, not value. This is important when binding to an
* array of objects. See an example [in this jsfiddle](http://jsfiddle.net/qWzTb/).
* </div>
*
* Optionally, a single hard-coded `<option>` element, with the value set to an empty string, can
* be nested into the `<select>` element. This element will then represent the `null` or "not selected"
* option. See example below for demonstration.
*
* <div class="alert alert-warning">
* **Note:** `ngOptions` provides an iterator facility for the `<option>` element which should be used instead
* of {@link ng.directive:ngRepeat ngRepeat} when you want the
* `select` model to be bound to a non-string value. This is because an option element can only
* be bound to string values at present.
* **Note:** `ngModel` compares by reference, not value. This is important when binding to an
* array of objects. See an example [in this jsfiddle](http://jsfiddle.net/qWzTb/).
* </div>
*
* <div class="alert alert-info">
* **Note:** Using `select as` will bind the result of the `select as` expression to the model, but
* ## `select as`
*
* Using `select as` will bind the result of the `select as` expression to the model, but
* the value of the `<select>` and `<option>` html elements will be either the index (for array data sources)
* or property name (for object data sources) of the value within the collection.
* </div>
* or property name (for object data sources) of the value within the collection. If a `track by` expression
* is used, the result of that expression will be set as the value of the `option` and `select` elements.
*
* ### `select as` with `trackexpr`
*
* Using `select as` together with `trackexpr` is not recommended. Reasoning:
*
* **Note:** Using `select as` together with `trackexpr` is not recommended.
* Reasoning:
* - Example: &lt;select ng-options="item.subItem as item.label for item in values track by item.id" ng-model="selected"&gt;
* values: [{id: 1, label: 'aLabel', subItem: {name: 'aSubItem'}}, {id: 2, label: 'bLabel', subItem: {name: 'bSubItem'}}],
* $scope.selected = {name: 'aSubItem'};