144 lines
9.7 KiB
HTML
Executable file
144 lines
9.7 KiB
HTML
Executable file
<a href="http://github.com/angular/angular.js/tree/v1.2.0rc1/src/ng/directive/select.js#L3" class="view-source btn btn-action"><i class="icon-zoom-in"> </i> View source</a><a href="http://github.com/angular/angular.js/edit/master/src/ng/directive/select.js" class="improve-docs btn btn-primary"><i class="icon-edit"> </i> Improve this doc</a><h1><code ng:non-bindable="">select</code>
|
|
<div><span class="hint">directive in module <code ng:non-bindable="">ng</code>
|
|
</span>
|
|
</div>
|
|
</h1>
|
|
<div><h2 id="Description">Description</h2>
|
|
<div class="description"><div class="ng-directive-page ng-directive-select-page"><p>HTML <code>SELECT</code> element with angular data-binding.</p>
|
|
<h3><code>ngOptions</code></h3>
|
|
<p>Optionally <code>ngOptions</code> attribute can be used to dynamically generate a list of <code><option></code>
|
|
elements for a <code><select></code> element using an array or an object obtained by evaluating the
|
|
<code>ngOptions</code> expression.</p>
|
|
<p>When an item in the <code><select></code> menu is selected, the value of array element or object property
|
|
represented by the selected option will be bound to the model identified by the <code>ngModel</code>
|
|
directive of the parent select element.</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 <code>null</code> or "not selected"
|
|
option. See example below for demonstration.</p>
|
|
<p>Note: <code>ngOptions</code> provides iterator facility for <code><option></code> element which should be used instead
|
|
of <a href="api/ng.directive:ngRepeat"><code>ngRepeat</code></a> when you want the
|
|
<code>select</code> model to be bound to a non-string value. This is because an option element can currently
|
|
be bound to string values only.</p>
|
|
</div></div>
|
|
<h2 id="Usage">Usage</h2>
|
|
<div class="usage"><p>This directive can be used as custom element, but be aware of <a href="guide/ie">IE restrictions</a>.</p>as element:<pre class="prettyprint linenums"><select
|
|
ngModel="{string}"
|
|
[name="{string}"]
|
|
[required]
|
|
[ngRequired="{string}"]
|
|
[ngOptions="{comprehension_expression}"]>
|
|
</select></pre>
|
|
<h4 id="parameters">Parameters</h4><table class="variables-matrix table table-bordered table-striped"><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><div class="ng-directive-page ng-directive-select-page"><p>Assignable angular expression to data-bind to.</p>
|
|
</div></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><div class="ng-directive-page ng-directive-select-page"><p>Property name of the form under which the control is published.</p>
|
|
</div></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><div class="ng-directive-page ng-directive-select-page"><p>The control is considered valid only if value is entered.</p>
|
|
</div></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><div class="ng-directive-page ng-directive-select-page"><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>
|
|
</div></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><div class="ng-directive-page ng-directive-select-page"><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>select</code> <strong><code>as</code></strong> <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>
|
|
</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>).</li>
|
|
</ul>
|
|
</div></td></tr></tbody></table></div>
|
|
<h2 id="Example">Example</h2>
|
|
<div class="example"><div class="ng-directive-page ng-directive-select-page"><h4>Source</h2>
|
|
<div source-edit="" source-edit-deps="angular.js script.js" source-edit-html="index.html-106" source-edit-css="" source-edit-js="script.js-105" source-edit-json="" source-edit-unit="" source-edit-scenario="scenario.js-107"></div>
|
|
<div class="tabbable"><div class="tab-pane" title="index.html">
|
|
<pre class="prettyprint linenums" ng-set-text="index.html-106" ng-html-wrap=" angular.js script.js"></pre>
|
|
<script type="text/ng-template" id="index.html-106">
|
|
|
|
<div ng-controller="MyCntrl">
|
|
<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="color" ng-options="c.name for c in colors"></select><br>
|
|
|
|
Color (null allowed):
|
|
<span class="nullable">
|
|
<select ng-model="color" ng-options="c.name for c in colors">
|
|
<option value="">-- chose color --</option>
|
|
</select>
|
|
</span><br/>
|
|
|
|
Color grouped by shade:
|
|
<select ng-model="color" ng-options="c.name group by c.shade for c in colors">
|
|
</select><br/>
|
|
|
|
|
|
Select <a href ng-click="color={name:'not in list'}">bogus</a>.<br>
|
|
<hr/>
|
|
Currently selected: {{ {selected_color:color} }}
|
|
<div style="border:solid 1px black; height:20px"
|
|
ng-style="{'background-color':color.name}">
|
|
</div>
|
|
</div>
|
|
</script>
|
|
</div>
|
|
<div class="tab-pane" title="script.js">
|
|
<pre class="prettyprint linenums" ng-set-text="script.js-105"></pre>
|
|
<script type="text/ng-template" id="script.js-105">
|
|
function MyCntrl($scope) {
|
|
$scope.colors = [
|
|
{name:'black', shade:'dark'},
|
|
{name:'white', shade:'light'},
|
|
{name:'red', shade:'dark'},
|
|
{name:'blue', shade:'dark'},
|
|
{name:'yellow', shade:'light'}
|
|
];
|
|
$scope.color = $scope.colors[2]; // red
|
|
}
|
|
</script>
|
|
</div>
|
|
<div class="tab-pane" title="End to end test">
|
|
<pre class="prettyprint linenums" ng-set-text="scenario.js-107"></pre>
|
|
<script type="text/ng-template" id="scenario.js-107">
|
|
it('should check ng-options', function() {
|
|
expect(binding('{selected_color:color}')).toMatch('red');
|
|
select('color').option('0');
|
|
expect(binding('{selected_color:color}')).toMatch('black');
|
|
using('.nullable').select('color').option('');
|
|
expect(binding('{selected_color:color}')).toMatch('null');
|
|
});
|
|
</script>
|
|
</div>
|
|
</div><h2>Demo</h4>
|
|
<div class="well doc-example-live animate-container" ng-embed-app="" ng-set-html="index.html-106" ng-eval-javascript="script.js-105"></div>
|
|
</div></div>
|
|
</div>
|