Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bigopon/aurelia-v2-virtual-repeat
A virtualization plugin for Aurelia 2
https://github.com/bigopon/aurelia-v2-virtual-repeat
aurelia
Last synced: 8 days ago
JSON representation
A virtualization plugin for Aurelia 2
- Host: GitHub
- URL: https://github.com/bigopon/aurelia-v2-virtual-repeat
- Owner: bigopon
- Created: 2021-03-23T11:03:15.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-02-17T18:49:34.000Z (almost 3 years ago)
- Last Synced: 2024-12-13T19:26:27.100Z (about 1 month ago)
- Topics: aurelia
- Language: TypeScript
- Homepage: https://aurelia-v2-virtual-repeat.vercel.app
- Size: 945 KB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# aurelia-v2-virtual-repeat
A plugin for doing virtualization with Aurelia 2
[DEMO](https://aurelia-v2-virtual-repeat.vercel.app/)
Size:
- Minified: 12KB
- Minified + gzip: 4KB
## Installation
To install the plugin, do:
```
npm install aurelia-v2-virtual-repeat
```
To register the standard behavior of the plugin in your application, add `DefaultVirtualRepeatConfiguration` to your Aurelia instance:
```ts
import { DefaultVirtualRepeatConfiguration } from 'aurelia-v2-virtual-repeat';
Aurelia.register(DefaultVirtualRepeatConfiguration).app(MyApp).start();
```
## Usage
### Standard usages:
This plugin can be used like the standard repeater, like in the following example:
#### With div
```html
${$index} ${item}
```
#### With table
```html
${$index}
${item}
```
#### With ordered/unordered lists
```html
-
${$index} ${item}
```
### Note:
The `virtual-repeat` requires to be placed inside a "scrollable" element, which means the element should have either `overflow: scroll` or `overflow: auto` in its styles. An error will be throw if the `virtual-repeat` is unable to locate such element.
## Caveats
1. There's only a single mode for the attribute `virtual-repeat`: DOM recycling mode. In this mode, it is expected that the DOM nodes will be moved around, and only binding data will be changed. Application should be aware of this and employ reactive programming model with change handler `xxxxxChanged()` to avoid surprises.
2. `` is not supported as a root of a repeat template, use a normal element instead
3. Similar to (1), beware of `:nth-child` and similar CSS selectors. This implementation requires appropriate shifting visible items, based on scroll position. This means DOM elements order will not stay the same, thus creating unexpected `:nth-child` CSS selector behavior. To work around this, you can use contextual properties `$index`, `$odd`, `$even`, `$first`, `$last`, `$middle`, `$length` to determine the position of an item, and apply CSS classes/styles against it, like the following example:
```html
${person.name}
```
4. Similar to (2), other template controllers cannot be used in conjunction with the `virtual-repeat`, unlike the standard `repeat`. I.e: built-in template controllers: `with`, `if`, `au-slot` cannot be used with the `virtual-repeat`. This can be workaround'd by nesting other template controllers inside the repeated element, with `` element, for example:
```html
${message}
Person name is: ${name}
```
## Plugin Development & Contribution
To develop the plugin, run
```
npm run test
```
Run unit tests in watch mode.
```
npm run test:watch
```
## Development plan
- This plugin is a way to provide the feature earlier for those who need, and later will be incorporated into the core of Aurelia v2.
- Only a single DOM recycling, same items height assumed mode is supported with the `virtual-repeat` attribute at the moment. In the future, there will be more: non-recycling mode, variable height, and maybe an additional of `` custom element for more control over the behavior of the repeat.
- Only array/null/undefined are supported at the moment, `Set` & `Map` are harder as they require better collection to index mapping
- Infinite scrolling is not supported yet, if there's a need to load more items, can listen to the scroll even on the scroller element, and invoke the item retrieval calls
- Virtualization on the whole page (document mode) support is removed. If there's enough demand, it will be added back.
- Cross shadow DOM boundary virtualization is not supported, as the algorithm for determining the scroller element is more comlex, though it should be doable.
## TODO:
- [ ] More tests
- [ ] Infinite scrolling aka load more (v1)
- [ ] Variable height mode
- [ ] Listenable events
- [ ] Non dom-recycling mode
- [ ] Cross shadow DOM boundary
- [ ] Custom element
- [ ] Set/Map support
- [ ] Whole page mode