@angular-wave/angular.ts 0.9.4 → 0.9.6

package/src/directive/options/options.md

@@ -1,179 +0,0 @@
-/\*\*
-
--
-- The `ngOptions` attribute can be used to dynamically generate a list of `<option>`
-- elements for the `<select>` element using the array or object obtained by evaluating the
-- `ngOptions` comprehension expression.
--
-- In many cases, {@link ng.directive:ngRepeat ngRepeat} can be used on `<option>` elements instead of
-- `ngOptions` to achieve a similar result. However, `ngOptions` provides some beneits:
-- - more flexibility in how the `<select>`'s model is assigned via the `select` **`as`** part of the
-- comprehension expression
-- - reduced memory consumption by not creating a new scope for each repeated instance
-- - increased render speed by creating the options in a documentFragment instead of individually
--
-- 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.
--
-- 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.
--
-- ## Complex Models (objects or collections)
--
-- By default, `ngModel` watches the model by reference, not value. This is important to know when
-- binding the select to a model that is an object or a collection.
--
-- One issue occurs if you want to preselect an option. For example, if you set
-- the model to an object that is equal to an object in your collection, `ngOptions` won't be able to set the selection,
-- because the objects are not identical. So by default, you should always reference the item in your collection
-- for preselections, e.g.: `$scope.selected = $scope.collection[3]`.
--
-- Another solution is to use a `track by` clause, because then `ngOptions` will track the identity
-- of the item not by reference, but by the result of the `track by` expression. For example, if your
-- collection items have an id property, you would `track by item.id`.
--
-- A different issue with objects or collections is that ngModel won't detect if an object property or
-- a collection item changes. For that reason, `ngOptions` additionally watches the model using
-- `$watchCollection`, when the expression contains a `track by` clause or the the select has the `multiple` attribute.
-- This allows ngOptions to trigger a re-rendering of the options even if the actual object/collection
-- has not changed identity, but only a property on the object or an item in the collection changes.
--
-- Note that `$watchCollection` does a shallow comparison of the properties of the object (or the items in the collection
-- if the model is an array). This means that changing a property deeper than the first level inside the
-- object/collection will not trigger a re-rendering.
--
-- ## `select` **`as`**
--
-- Using `select` **`as`** will bind the result of the `select` 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. 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`** and **`track by`**
--
-- <div class="alert alert-warning">
-- Be careful when using `select` **`as`** and **`track by`** in the same expression.
-- </div>
--
-- Given this array of items on the $scope:
--
-- ```js
-
-  ```
-
-- $scope.items = [{
-- id: 1,
-- label: 'aLabel',
-- subItem: { name: 'aSubItem' }
-- }, {
-- id: 2,
-- label: 'bLabel',
-- subItem: { name: 'bSubItem' }
-- }];
-- ```
-
-  ```
-
--
-- This will work:
--
-- ```html
-
-  ```
-
-- <select ng-options="item as item.label for item in items track by item.id" ng-model="selected"></select>
-- ```
-
-  ```
-
-- ```js
-
-  ```
-
-- $scope.selected = $scope.items[0];
-- ```
-
-  ```
-
--
-- but this will not work:
--
-- ```html
-
-  ```
-
-- <select ng-options="item.subItem as item.label for item in items track by item.id" ng-model="selected"></select>
-- ```
-
-  ```
-
-- ```js
-
-  ```
-
-- $scope.selected = $scope.items[0].subItem;
-- ```
-
-  ```
-
--
-- In both examples, the **`track by`** expression is applied successfully to each `item` in the
-- `items` array. Because the selected option has been set programmatically in the controller, the
-- **`track by`** expression is also applied to the `ngModel` value. In the first example, the
-- `ngModel` value is `items[0]` and the **`track by`** expression evaluates to `items[0].id` with
-- no issue. In the second example, the `ngModel` value is `items[0].subItem` and the **`track by`**
-- expression evaluates to `items[0].subItem.id` (which is undefined). As a result, the model value
-- is not matched against any `<option>` and the `<select>` appears as having no selected value.
--
--
-- @param {string} ngModel Assignable AngularTS expression to data-bind to.
-- @param {string} ngOptions in one of the following forms:
--
-- - for array data sources:
--     * `label` **`for`** `value` **`in`** `array`
--     * `select` **`as`** `label` **`for`** `value` **`in`** `array`
--     * `label` **`group by`** `group` **`for`** `value` **`in`** `array`
--     * `label` **`disable when`** `disable` **`for`** `value` **`in`** `array`
--     * `label` **`group by`** `group` **`for`** `value` **`in`** `array` **`track by`** `trackexpr`
--     * `label` **`disable when`** `disable` **`for`** `value` **`in`** `array` **`track by`** `trackexpr`
--     * `label` **`for`** `value` **`in`** `array` | orderBy:`orderexpr` **`track by`** `trackexpr`
--        (for including a filter with `track by`)
-- - for object data sources:
--     * `label` **`for (`**`key` **`,`** `value`**`) in`** `object`
--     * `select` **`as`** `label` **`for (`**`key` **`,`** `value`**`) in`** `object`
--     * `label` **`group by`** `group` **`for (`**`key`**`,`** `value`**`) in`** `object`
--     * `label` **`disable when`** `disable` **`for (`**`key`**`,`** `value`**`) in`** `object`
--     * `select` **`as`** `label` **`group by`** `group`
--         **`for` `(`**`key`**`,`** `value`**`) in`** `object`
--     * `select` **`as`** `label` **`disable when`** `disable`
--         **`for` `(`**`key`**`,`** `value`**`) in`** `object`
--
-- Where:
--
-- - `array` / `object`: an expression which evaluates to an array / object to iterate over.
-- - `value`: local variable which will refer to each item in the `array` or each property value
--      of `object` during iteration.
-- - `key`: local variable which will refer to a property name in `object` during iteration.
-- - `label`: The result of this expression will be the label for `<option>` element. The
--     `expression` will most likely refer to the `value` variable (e.g. `value.propertyName`).
-- - `select`: The result of this expression will be bound to the model of the parent `<select>`
--      element. If not specified, `select` expression will default to `value`.
-- - `group`: The result of this expression will be used to group options using the `<optgroup>`
--      DOM element.
-- - `disable`: The result of this expression will be used to disable the rendered `<option>`
--      element. Return `true` to disable.
-- - `trackexpr`: Used when working with an array of objects. The result of this expression will be
--      used to identify the objects in the array. The `trackexpr` will most likely refer to the
--     `value` variable (e.g. `value.propertyName`). With this the selection is preserved
--      even when the options are recreated (e.g. reloaded from the server).
-- @param {string=} name Property name of the form under which the control is published.
-- @param {string=} required The control is considered valid only if value is entered.
-- @param {string=} ngRequired Adds `required` attribute and `required` validation constraint to
-- the element when the ngRequired expression evaluates to true. Use `ngRequired` instead of
-- `required` when you want to data-bind to the `required` attribute.
-- @param {string=} ngAttrSize sets the size of the select element dynamically. Uses the
-- {@link guide/interpolation#-ngattr-for-binding-to-arbitrary-attributes ngAttr} directive.
-- \*/