|
| 1 | +/** |
| 2 | + * @ngdoc directive |
| 3 | + * @module ionic |
| 4 | + * @name collectionRepeat |
| 5 | + * @restrict A |
| 6 | + * @description |
| 7 | + * `collection-repeat` is a directive that allows you to render lists with |
| 8 | + * thousands of items in them, and experience little to no performance penalty. |
| 9 | + * |
| 10 | + * Demo: |
| 11 | + * |
| 12 | + * The directive renders onto the screen only the items that should be currently visible. |
| 13 | + * So if you have 1,000 items in your list but only ten fit on your screen, |
| 14 | + * collection-repeat will only render into the DOM the ten that are in the current |
| 15 | + * scroll position. |
| 16 | + * |
| 17 | + * Here are a few things to keep in mind while using collection-repeat: |
| 18 | + * |
| 19 | + * 1. The data supplied to collection-repeat must be an array. |
| 20 | + * 2. You must explicitly tell the directive what size your items will be in the DOM |
| 21 | + * (pixel amount or percentage), using directive attributes (see below). |
| 22 | + * 3. The elements rendered will be absolutely positioned: be sure to let your CSS work with this (see below). |
| 23 | + * 4. Keep the HTML of your repeated elements as simple as possible. As the user scrolls down, elements |
| 24 | + * will be lazily compiled. Resultingly, the more complicated your elements, the more likely it is that |
| 25 | + * the on-demand compilation will cause jankiness in the user's scrolling. |
| 26 | + * 5. The more elements you render on the screen at a time, the slower the scrolling will be. |
| 27 | + * It is recommended to keep grids of collection-repeat list elements at 3-wide or less. |
| 28 | + * 6. Each collection-repeat list will take up all of its parent scrollView's space. |
| 29 | + * If you wish to have multiple lists on one page, put each list within its own |
| 30 | + * {@link ionic.directive:ionScroll ionScroll} container. |
| 31 | + * |
| 32 | + * |
| 33 | + * |
| 34 | + * @usage |
| 35 | + * |
| 36 | + * #### Basic Usage (single rows of items) |
| 37 | + * |
| 38 | + * Notice two things here: we use ng-style to set the height of the item to match |
| 39 | + * what the repeater thinks our item height is. Additionally, we add a css rule |
| 40 | + * to make our item stretch to fit the full screen (since it will be absolutely |
| 41 | + * positioned). |
| 42 | + * |
| 43 | + * ```html |
| 44 | + * <ion-content ng-controller="ContentCtrl"> |
| 45 | + * <div class="list"> |
| 46 | + * <div class="item my-item" |
| 47 | + * collection-repeat="item in items" |
| 48 | + * collection-item-width="100%" |
| 49 | + * collection-item-height="getItemHeight(item, $index)" |
| 50 | + * ng-style="{height: getItemHeight(item, $index)}"> |
| 51 | + * {% raw %}{{item}}{% endraw %} |
| 52 | + * </div> |
| 53 | + * </div> |
| 54 | + * </div> |
| 55 | + * ``` |
| 56 | + * ```js |
| 57 | + * function ContentCtrl($scope) { |
| 58 | + * $scope.items = []; |
| 59 | + * for (var i = 0; i < 1000; i++) { |
| 60 | + * $scope.items.push('Item ' + i); |
| 61 | + * } |
| 62 | + * |
| 63 | + * $scope.getItemHeight = function(item, index) { |
| 64 | + * //Make evenly indexed items be 10px taller, for the sake of example |
| 65 | + * return (index % 2) === 0 ? 50 : 60; |
| 66 | + * }; |
| 67 | + * } |
| 68 | + * ``` |
| 69 | + * ```css |
| 70 | + * .my-item { |
| 71 | + * left: 0; |
| 72 | + * right: 0; |
| 73 | + * } |
| 74 | + * ``` |
| 75 | + * |
| 76 | + * #### Grid Usage (three items per row) |
| 77 | + * |
| 78 | + * ```html |
| 79 | + * <ion-content> |
| 80 | + * <div class="item item-avatar my-image-item" |
| 81 | + * collection-repeat="image in images" |
| 82 | + * collection-item-width="33%" |
| 83 | + * collection-item-height="33%"> |
| 84 | + * <img ng-src="{{image.src}}"> |
| 85 | + * </div> |
| 86 | + * </ion-content> |
| 87 | + * ``` |
| 88 | + * ```css |
| 89 | + * .my-image-item { |
| 90 | + * height: 33%; |
| 91 | + * width: 33%; |
| 92 | + * } |
| 93 | + * ``` |
| 94 | + * |
| 95 | + * @param {expression} collection-repeat The expression indicating how to enumerate a collection. These |
| 96 | + * formats are currently supported: |
| 97 | + * |
| 98 | + * * `variable in expression` – where variable is the user defined loop variable and `expression` |
| 99 | + * is a scope expression giving the collection to enumerate. |
| 100 | + * |
| 101 | + * For example: `album in artist.albums`. |
| 102 | + * |
| 103 | + * * `variable in expression track by tracking_expression` – You can also provide an optional tracking function |
| 104 | + * which can be used to associate the objects in the collection with the DOM elements. If no tracking function |
| 105 | + * is specified the collection-repeat associates elements by identity in the collection. It is an error to have |
| 106 | + * more than one tracking function to resolve to the same key. (This would mean that two distinct objects are |
| 107 | + * mapped to the same DOM element, which is not possible.) Filters should be applied to the expression, |
| 108 | + * before specifying a tracking expression. |
| 109 | + * |
| 110 | + * For example: `item in items` is equivalent to `item in items track by $id(item)'. This implies that the DOM elements |
| 111 | + * will be associated by item identity in the array. |
| 112 | + * |
| 113 | + * For example: `item in items track by $id(item)`. A built in `$id()` function can be used to assign a unique |
| 114 | + * `$$hashKey` property to each item in the array. This property is then used as a key to associated DOM elements |
| 115 | + * with the corresponding item in the array by identity. Moving the same object in array would move the DOM |
| 116 | + * element in the same way in the DOM. |
| 117 | + * |
| 118 | + * For example: `item in items track by item.id` is a typical pattern when the items come from the database. In this |
| 119 | + * case the object identity does not matter. Two objects are considered equivalent as long as their `id` |
| 120 | + * property is same. |
| 121 | + * |
| 122 | + * For example: `item in items | filter:searchText track by item.id` is a pattern that might be used to apply a filter |
| 123 | + * to items in conjunction with a tracking expression. |
| 124 | + * |
| 125 | + * @param {expression} collection-item-width The width of the repeated element. Can be a number (in pixels) or a percentage. |
| 126 | + * @param {expression} collection-item-height The height of the repeated element. Can be a number (in pixels), or a percentage. |
| 127 | + * |
| 128 | + */ |
1 | 129 | IonicModule |
2 | 130 | .directive('collectionRepeat', [ |
3 | 131 | '$collectionRepeatManager', |
|
0 commit comments