https://github.com/gullerya/data-tier-list
List component based on DataTier binding engine
https://github.com/gullerya/data-tier-list
Last synced: about 2 months ago
JSON representation
List component based on DataTier binding engine
- Host: GitHub
- URL: https://github.com/gullerya/data-tier-list
- Owner: gullerya
- License: isc
- Created: 2018-09-09T05:49:43.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2023-11-19T10:31:45.000Z (over 1 year ago)
- Last Synced: 2025-03-13T09:52:56.173Z (3 months ago)
- Language: JavaScript
- Size: 514 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: readme.md
- Funding: .github/FUNDING.yml
- License: license.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/data-tier-list)
[](./license.md)
[](https://codecov.io/gh/gullerya/data-tier-list/branch/master)
[](https://app.codacy.com/app/gullerya/data-tier-list)
# `data-tier-list`
`data-tier-list` is a WebComponent, that provides repetative view functionality given any HTML template and a data set.
Main features and concepts:
- supported data set types: `Array`, `Object`
- if a provided data set is is not an [observable](https://github.com/gullerya/object-observer/blob/master/docs/observable.md), it is transformed (cloned) into such one
- data set mutations are observed and reflected
- template mutations are observed and reflected
- uniformity of a data items __is not__ validated/enforced
`data-tier-list` relies on a [data-tier](https://github.com/gullerya/data-tier) library for the model-view tying part.
`data-tier-list`'s HTML binding declaration API adheres to the `data-tier`'s one [here](https://github.com/gullerya/data-tier/blob/main/docs/api-tying-declaration.md). See specific details below, in [API section](#api).
#### Changelog is [here](docs/changelog.md).
## Preview
For a preview/playground you are welcome to:
- [CodePen](https://codepen.io/gullerya/pen/abVYKJB) of a simple exapmle of list of primitive values
- [CodePen](https://codepen.io/gullerya/pen/ZEaxvRZ) of a more involved example of list of rows, table of data
## Install
Use regular `npm install data-tier-list --save-prod` to use the library from your local environment:
```js
import 'node_modules/data-tier-list/dist/data-tier-list.min.js';
```
Alternatively, a __CDN__ deployment available (AWS driven), so one can import it directly:
```js
import 'https://libs.gullerya.com/data-tier-list/x.y.z/data-tier-list.min.js';
```
> Note: replace the `x.y.z` by the desired version, one of the listed in the [changelog](docs/changelog.md).
CDN features:
- HTTPS only, no untrusted man-in-the-middle
- highly available (with many geo spread edges)
- agressive caching setup
> CDN disro is accompanied with [SRI hashes](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity),
that are found in the `sri.json` file.
Browse to the relevant version's file revision by this example - `https://github.com/gullerya/data-tier-list/blob/v2.2.1/sri.json`,
while replacing the `2.2.1` part with the relevant one.
## API
`data-tier-list`'s HTML binding declaration API adheres to the `data-tier`'s one [here](https://github.com/gullerya/data-tier/blob/main/docs/api-tying-declaration.md).
### Data
The dataset of items is set/updated via the `items` property of the `data-tier-list` element, for example:
```js
.items = [ 1, 2, 3 ];
```
`items` elements can be anything from primitive values to complex object structures.
Each item will be shown according to the __item template__.
### View
Light DOM of the `data-tier-list` serves as a __template__ for a single item.
`data-tier-list` element self and its light DOM __are not__ displayed.
Details:
- within a template use binding declaration syntax is as [here](https://github.com/gullerya/data-tier/blob/main/docs/api-tying-declaration.md), with `item` as scope key (see examples below)
- template is observed for any changes; replacement of it or a change of its child/ren triggers a __full (re)render__ of the list
- template may have __at most__ one top level element (any nested elements tree allowed)
- template removal cleans the list
- template errors (eg more than one child) leave list untouched
### Examples
#### List of bands
```html
```
And then supply data:
```js
const dtl = document.querySelector('data-tier-list');
dtl.items = [
{ title: '..', fromYear: 1991, albumsTotal: 3 },
{ title: '..', fromYear: 1992, albumsTotal: 5 },
{ title: '..', fromYear: 1993, albumsTotal: 7 }
]
```