vscroll-native

vscroll-native is a JavaScript library built on top of the vscroll library to represent unlimited datasets using virtualization technique. The idea behind virtualization is to increase the performance of large scrollable lists by rendering only a small portion of the dataset, which is visible to the end user at a moment, while the rest of the dataset is emulated with special padding elements that keep the scrollbar parameters consistent, making the UX close to a simple scrollable list without virtualization.

• Getting
• Usage
  • Viewport
  • Template
  • Datasource
• Adapter
• Development

Getting

CDN

<script src="https://cdn.jsdelivr.net/npm/vscroll-native"></script>
<script>
  const scroller = new VScrollNative.Scroller({...});
</script>

NPM

npm install vscroll-native

import { Scroller } from 'vscroll-native';

const scroller = new Scroller({...});

Usage

The vscroll-native module exports two entities: Scroller and Datasource. The virtual scroll engine runs during the Scroller class instantiation. The constructor of the Scroller class requires 3 arguments packed in a settings object: viewport HTML element, single item HTML template factory and the datasource.

import { Scroller, Datasource } from 'vscroll-native';

const element = document.getElementById('viewport');

const template = item =>
  `<div class="item"><span>${item.data.id}</span>) ${item.data.text}</div>`;

const datasource = new Datasource({
  get: (index, length, success) => {
    const data = [];
    for (let i = index; i <= index + count - 1; i++) {
      const item: Data = { id: i, text: 'item #' + i };
      data.push(item);
    }
    success(data);
  }
});

new Scroller({ element, datasource, template });

This basic example is available at https://dhilt.github.io/vscroll-native/samples/cdn/. Let's clarify what the Scroller is and how to instantiate it properly. In terms of the TypeScript the argument object of the Scroller constructor has the following type:

interface IScrollerParams<Data = unknown> {
  element: HTMLElement;
  template: Template<Data>;
  datasource: IDatasource<Data>;
}

1. Viewport

The first parameter of the Scroller is an HTML element that should provide the limited viewport with scrollable contents. It should be present in DOM before instantiating the Scroller.

const element = document.getElementById('viewport');

<div id="viewport"></div>

#viewport {
  height: 240px;
  width: 150px;
  overflow-y: scroll;
}

This is the simplest case with the default elements structure that is managed by the Scroller automatically.

2. Template

The second parameter of the Scroller is a factory of single item template. This is a function that should return a string that will be used by the Scroller to render items in the visible part of the viewport.

const template = ({ data }) =>
  `<div class="item"><span>${data.id}</span>) ${data.text}</div>`;

The argument of the template factory is an item object containing data to be present to the end user. With TypeScript it can be written as follows:

import { Template } from 'vscroll-native';

interface Data {
  id: number;
  text: string;
}

const template: Template<Data> = ({ data }) =>
  `<div class="item"><span>${data.id}</span>) ${data.text}</div>`;

3. Datasource

The third parameter of the Scroller is a special datasource object, providing dataset items in runtime. There are two ways of how it can be defined. First, as an object literal of IDatasource type:

import { IDatasource } from 'vscroll-native';

const datasource: IDatasource<Data> = { get, settings };

Second, as an instance of Datasource class, whose constructor requires an object of IDatasource type:

import { Datasource } from 'vscroll-native';

const datasource = new Datasource<Data>({ get, settings });

The second way makes the Adapter API available via datasource.adapter property after the Datasource is instantiated (see Adapter section). In both cases we need to arrange the object of IDatasource type:

interface IDatasource<Data = unknown> {
  get: DatasourceGet<Data>;
  settings?: Settings<Data>;
  devSettings?: DevSettings;
}

The settings parameter is optional (as well as devSettings), please refer to ngx-ui-scroll documentation to get more information about it: https://github.com/dhilt/ngx-ui-scroll#settings.

The get parameter is the main point of the App-Scroller integration. It should provide a portion of dataset by index and count:

const get = <Data = unknown>(
  index: number, count: number, success: (data: Data[]) => void
) => 
  success(Array.from({ length: count }).map((i, j) =>
    ({ id: index + j, text: 'item #' + (index + j) })
  ));

This is the simplest example of the synchronous Datasource.get implementation, where items are generated at runtime and passed to the Scroller via success callback. There are two additional signatures for asynchronous implementations: promise-based and observable-based.

const get = (index, count) => new Promise((resolve, reject) => {
  makeAjaxCall(index, count)
    .then(data => resolve(data))
    .catch(error => reject(error))
});
// should be equivalent to 
// const get = (index, count) => makeAjaxCall(index, count);

import { Observable } from 'rxjs';

const get = (index, count) => new Observable(subscriber => {
  makeAjaxCall(index, count)
    .then(data => subscriber.next(data))
    .catch(error => subscriber.error(error))
    .finally(() => subscriber.complete())
});

Adapter

Adapter is a special entity providing massive functionality to assess and manipulate Scroller's data/parameters at runtime. It is available if the Datasource is created via operator new.

import { Datasource, Scroller } from 'vscroll-native';

const ds = new Datasource({ ... });

ds.adapter.init$.once(() => console.log('Adapter works, the second output'));

new Scroller({ datasource: ds, ... });

console.log('Scroller works, the first output');

Note, that the adapter subscriptions become available right after instantiating the Datasource, but they start work only after the Scroller instantiation.

Please refer to the ngx-ui-scroll documentation for more information on the Adapter API: https://github.com/dhilt/ngx-ui-scroll#adapter-api. An important difference should be taken into account, this is how the reactive props are implemented:

• ngx-ui-scroll Adapter implements RxJs subjects,
• vscroll-native Adapter implements Reactive entities.

The vscroll-native demo contains some basic examples of the Adapter usage: https://dhilt.github.io/vscroll-native/.

Development

The vscroll-native module is built on top of the vscroll solution and can be treated as a vscroll wrapper or consumer. It is designed to demonstrate how the vscroll solution may work in non-specific environment. The sources of the vscroll-native module are relatively small (https://github.com/dhilt/vscroll-native/tree/main/src); they do

• instantiate the virtual scrolling Workflow (main entity of the vscroll module),
• advance DOM manipulations in accordance with the Workflow requirements,
• provide some infrastructure logic such as internal Workflow instance storage and external Scroller class.

The issues, requests and ideas that are not targeting these particular points should be addressed to the vscroll repository.

The most important point of the development of the vscroll-native module is the DOM-related logic. Another important area is the demo app development. Also, the tests are very poor and need extension.

There are some npm scripts:

• npm start, runs the demo app over the vscroll-native sources at 5000 port
• npm run build, builds the vscroll-native distributive
• npm run build-app, builds the demo app distributive
• npm test, performs linter and tests in a single run
• npm run jest, runs tests in a watch mode

2022 © Denis Hilt