EVOLUTION-MANAGER
Edit File: select.html
<a href='https://github.com/angular/angular.js/edit/v1.3.x/src/ng/directive/select.js?message=docs(select)%3A%20describe%20your%20change...#L4' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit"> </i>Improve this Doc</a> <a href='https://github.com/angular/angular.js/tree/v1.3.9/src/ng/directive/select.js#L4' class='view-source pull-right btn btn-primary'> <i class="glyphicon glyphicon-zoom-in"> </i>View Source </a> <header class="api-profile-header"> <h1 class="api-profile-header-heading">select</h1> <ol class="api-profile-header-structure naked-list step-list"> <li> - directive in module <a href="api/ng">ng</a> </li> </ol> </header> <div class="api-profile-description"> <p>HTML <code>SELECT</code> element with angular data-binding.</p> <h1 id="-ngoptions-"><code>ngOptions</code></h1> <p>The <code>ngOptions</code> attribute can be used to dynamically generate a list of <code><option></code> elements for the <code><select></code> element using the array or object obtained by evaluating the <code>ngOptions</code> comprehension expression.</p> <p>In many cases, <code>ngRepeat</code> can be used on <code><option></code> elements instead of <code>ngOptions</code> to achieve a similar result. However, <code>ngOptions</code> 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 <code><select></code>'s model is assigned via the <code>select</code> <strong><code>as</code></strong> part of the comprehension expression. <code>ngOptions</code> should be used when the <code><select></code> 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.</p> <p>When an item in the <code><select></code> menu is selected, the array element or object property represented by the selected option will be bound to the model identified by the <code>ngModel</code> directive.</p> <p>Optionally, a single hard-coded <code><option></code> element, with the value set to an empty string, can be nested into the <code><select></code> element. This element will then represent the <code>null</code> or "not selected" option. See example below for demonstration.</p> <div class="alert alert-warning"> <strong>Note:</strong> <code>ngModel</code> compares by reference, not value. This is important when binding to an array of objects. See an example <a href="http://jsfiddle.net/qWzTb/">in this jsfiddle</a>. </div> <h2 id="-select-as-"><code>select</code> <strong><code>as</code></strong></h2> <p>Using <code>select</code> <strong><code>as</code></strong> will bind the result of the <code>select</code> expression to the model, but the value of the <code><select></code> and <code><option></code> html elements will be either the index (for array data sources) or property name (for object data sources) of the value within the collection. If a <strong><code>track by</code></strong> expression is used, the result of that expression will be set as the value of the <code>option</code> and <code>select</code> elements.</p> <h3 id="-select-as-and-track-by-"><code>select</code> <strong><code>as</code></strong> and <strong><code>track by</code></strong></h3> <div class="alert alert-warning"> Do not use <code>select</code> <strong><code>as</code></strong> and <strong><code>track by</code></strong> in the same expression. They are not designed to work together. </div> <p>Consider the following example:</p> <pre><code class="lang-html"><select ng-options="item.subItem as item.label for item in values track by item.id" ng-model="selected"> </code></pre> <pre><code class="lang-js">$scope.values = [{ id: 1, label: 'aLabel', subItem: { name: 'aSubItem' } }, { id: 2, label: 'bLabel', subItem: { name: 'bSubItem' } }]; $scope.selected = { name: 'aSubItem' }; </code></pre> <p>With the purpose of preserving the selection, the <strong><code>track by</code></strong> expression is always applied to the element of the data source (to <code>item</code> in this example). To calculate whether an element is selected, we do the following:</p> <ol> <li>Apply <strong><code>track by</code></strong> to the elements in the array. In the example: <code>[1, 2]</code></li> <li>Apply <strong><code>track by</code></strong> to the already selected value in <code>ngModel</code>. In the example: this is not possible as <strong><code>track by</code></strong> refers to <code>item.id</code>, but the selected value from <code>ngModel</code> is <code>{name: 'aSubItem'}</code>, so the <strong><code>track by</code></strong> expression is applied to a wrong object, the selected element can't be found, <code><select></code> is always reset to the "not selected" option.</li> </ol> </div> <div> <h2>Directive Info</h2> <ul> <li>This directive executes at priority level 0.</li> </ul> <h2 id="usage">Usage</h2> <div class="usage"> <ul> <li>as element: <pre><code><select ng-model="" [name=""] [required=""] [ng-required=""] [ng-options=""]> ... </select></code></pre> </li> </div> <section class="api-section"> <h3>Arguments</h3> <table class="variables-matrix input-arguments"> <thead> <tr> <th>Param</th> <th>Type</th> <th>Details</th> </tr> </thead> <tbody> <tr> <td> ngModel </td> <td> <a href="" class="label type-hint type-hint-string">string</a> </td> <td> <p>Assignable angular expression to data-bind to.</p> </td> </tr> <tr> <td> name <div><em>(optional)</em></div> </td> <td> <a href="" class="label type-hint type-hint-string">string</a> </td> <td> <p>Property name of the form under which the control is published.</p> </td> </tr> <tr> <td> required <div><em>(optional)</em></div> </td> <td> <a href="" class="label type-hint type-hint-string">string</a> </td> <td> <p>The control is considered valid only if value is entered.</p> </td> </tr> <tr> <td> ngRequired <div><em>(optional)</em></div> </td> <td> <a href="" class="label type-hint type-hint-string">string</a> </td> <td> <p>Adds <code>required</code> attribute and <code>required</code> validation constraint to the element when the ngRequired expression evaluates to true. Use <code>ngRequired</code> instead of <code>required</code> when you want to data-bind to the <code>required</code> attribute.</p> </td> </tr> <tr> <td> ngOptions <div><em>(optional)</em></div> </td> <td> <a href="" class="label type-hint type-hint-comprehension_expression">comprehension_expression</a> </td> <td> <p>in one of the following forms:</p> <ul> <li>for array data sources:<ul> <li><code>label</code> <strong><code>for</code></strong> <code>value</code> <strong><code>in</code></strong> <code>array</code></li> <li><code>select</code> <strong><code>as</code></strong> <code>label</code> <strong><code>for</code></strong> <code>value</code> <strong><code>in</code></strong> <code>array</code></li> <li><code>label</code> <strong><code>group by</code></strong> <code>group</code> <strong><code>for</code></strong> <code>value</code> <strong><code>in</code></strong> <code>array</code></li> <li><code>label</code> <strong><code>group by</code></strong> <code>group</code> <strong><code>for</code></strong> <code>value</code> <strong><code>in</code></strong> <code>array</code> <strong><code>track by</code></strong> <code>trackexpr</code></li> <li><code>label</code> <strong><code>for</code></strong> <code>value</code> <strong><code>in</code></strong> <code>array</code> | orderBy:<code>orderexpr</code> <strong><code>track by</code></strong> <code>trackexpr</code> (for including a filter with <code>track by</code>)</li> </ul> </li> <li>for object data sources:<ul> <li><code>label</code> <strong><code>for (</code></strong><code>key</code> <strong><code>,</code></strong> <code>value</code><strong><code>) in</code></strong> <code>object</code></li> <li><code>select</code> <strong><code>as</code></strong> <code>label</code> <strong><code>for (</code></strong><code>key</code> <strong><code>,</code></strong> <code>value</code><strong><code>) in</code></strong> <code>object</code></li> <li><code>label</code> <strong><code>group by</code></strong> <code>group</code> <strong><code>for (</code></strong><code>key</code><strong><code>,</code></strong> <code>value</code><strong><code>) in</code></strong> <code>object</code></li> <li><code>select</code> <strong><code>as</code></strong> <code>label</code> <strong><code>group by</code></strong> <code>group</code> <strong><code>for</code> <code>(</code></strong><code>key</code><strong><code>,</code></strong> <code>value</code><strong><code>) in</code></strong> <code>object</code></li> </ul> </li> </ul> <p>Where:</p> <ul> <li><code>array</code> / <code>object</code>: an expression which evaluates to an array / object to iterate over.</li> <li><code>value</code>: local variable which will refer to each item in the <code>array</code> or each property value of <code>object</code> during iteration.</li> <li><code>key</code>: local variable which will refer to a property name in <code>object</code> during iteration.</li> <li><code>label</code>: The result of this expression will be the label for <code><option></code> element. The <code>expression</code> will most likely refer to the <code>value</code> variable (e.g. <code>value.propertyName</code>).</li> <li><code>select</code>: The result of this expression will be bound to the model of the parent <code><select></code> element. If not specified, <code>select</code> expression will default to <code>value</code>.</li> <li><code>group</code>: The result of this expression will be used to group options using the <code><optgroup></code> DOM element.</li> <li><code>trackexpr</code>: Used when working with an array of objects. The result of this expression will be used to identify the objects in the array. The <code>trackexpr</code> will most likely refer to the <code>value</code> variable (e.g. <code>value.propertyName</code>). With this the selection is preserved even when the options are recreated (e.g. reloaded from the server).</li> </ul> </td> </tr> </tbody> </table> </section> <h2 id="example">Example</h2><p> <div> <a ng-click="openPlunkr('examples/example-example95')" class="btn pull-right"> <i class="glyphicon glyphicon-edit"> </i> Edit in Plunker</a> <div class="runnable-example" path="examples/example-example95" module="selectExample"> <div class="runnable-example-file" name="index.html" language="html" type="html"> <pre><code><script> angular.module('selectExample', []) .controller('ExampleController', ['$scope', function($scope) { $scope.colors = [ {name:'black', shade:'dark'}, {name:'white', shade:'light'}, {name:'red', shade:'dark'}, {name:'blue', shade:'dark'}, {name:'yellow', shade:'light'} ]; $scope.myColor = $scope.colors[2]; // red }]); </script> <div ng-controller="ExampleController"> <ul> <li ng-repeat="color in colors"> Name: <input ng-model="color.name"> [<a href ng-click="colors.splice($index, 1)">X</a>] </li> <li> [<a href ng-click="colors.push({})">add</a>] </li> </ul> <hr/> Color (null not allowed): <select ng-model="myColor" ng-options="color.name for color in colors"></select><br> Color (null allowed): <span class="nullable"> <select ng-model="myColor" ng-options="color.name for color in colors"> <option value="">-- choose color --</option> </select> </span><br/> Color grouped by shade: <select ng-model="myColor" ng-options="color.name group by color.shade for color in colors"> </select><br/> Select <a href ng-click="myColor = { name:'not in list', shade: 'other' }">bogus</a>.<br> <hr/> Currently selected: {{ {selected_color:myColor} }} <div style="border:solid 1px black; height:20px" ng-style="{'background-color':myColor.name}"> </div> </div></code></pre> </div> <div class="runnable-example-file" name="protractor.js" type="protractor" language="js"> <pre><code>it('should check ng-options', function() { expect(element(by.binding('{selected_color:myColor}')).getText()).toMatch('red'); element.all(by.model('myColor')).first().click(); element.all(by.css('select[ng-model="myColor"] option')).first().click(); expect(element(by.binding('{selected_color:myColor}')).getText()).toMatch('black'); element(by.css('.nullable select[ng-model="myColor"]')).click(); element.all(by.css('.nullable select[ng-model="myColor"] option')).first().click(); expect(element(by.binding('{selected_color:myColor}')).getText()).toMatch('null'); });</code></pre> </div> <iframe class="runnable-example-frame" src="examples/example-example95/index.html" name="example-example95"></iframe> </div> </div> </p> </div>