npm package: @lemonadejs/data-grid
Description: The JavaScript data grid component using LemonadeJS is a lightweight and flexible tool that allows developers to create dynamic and interactive tables on web pages. The component supports dynamic data loading, sorting, filtering, and pagination, making it
Author: Contact
Latest version: 2.0.0

# Javascript Data Grid

[Official website and documentation is here](https://lemonadejs.net/components/data-grid)

Compatible with Vanilla JavaScript, LemonadeJS, React, Vue or Angular.

The JavaScript Data Grid is a lightweight library that effortlessly enables you to embed lightweight data grids into your applications. Compatible with Vanilla JavaScript, LemonadeJS, React, VueJS, and Angular, this versatile component allows you to conveniently load JSON data, define columns, and seamlessly render the grid within your HTML. Enjoy robust features like search, pagination, and editable rows, empowering you to build interactive and feature-rich data grid experiences.

## Features

-   Lightweight: The lemonade data grid is only about 4 KBytes;
-   Customizable: You can define columns and user-defined actions to suit your use case;
-   Reactive: Any changes to the underlying data are automatically applied to the HTML, making it easy to keep your grid up-to-date;
-   Integration: It can be used as a standalone library or integrated with any modern framework;

## Getting Started

You can install using NPM or using directly from a CDN.

### npm Installation

To install it in your project using npm, run the following command:

```bash
$ npm install @lemonadejs/data-grid
```

### CDN

To use data grid via a CDN, include the following script tags in your HTML file:

```html
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/lemonadejs/dist/lemonade.min.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@lemonadejs/data-grid/dist/index.min.js"></script>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@lemonadejs/data-grid/dist/style.min.css" />
```

### Settings

| Attribute | Description |
| --- | --- |
| data: object[] | The data that will be displayed on the grid based on the columns attribute. |
| columns: columnItem[] | Each columnItem object represents a column of data to be displayed. For more information about this object, please refer to the 'Column Item' section below. |
| pagination?: Number | Enable the pagination and define the number of items per page. | 
| search?: Boolean | Enable the search. `Default: false` |
| editable?: Boolean | The grid is editable. `Default: false` |
| resizable?: Boolean | Enable the resizable functionality, allowing the columns to be resized. `Default: false` |
| zebra?: Boolean | Enable the zebra style, highlighting every odd row with a darker color. `Default: false` |
| url?: String | Specifies the URL for fetching the data. |
| remote?: Boolean | Enable the remote functionality. `Default: false` |

### Column Item

The columns property regulates the presentation of columns on the JavaScript data grid, specifying characteristics such as the sequence of columns, their width, and the positioning of data within them.  

| Option                | Description |
| --------------------- | ----------- |
| **name**?: string     | Determines the key of the data object to which the column refers. |
| **title**: string     | Required. Determines the text that will be displayed in the column Header. |
| **width**?: string    | This option specifies the width of the column and should be provided as a string with the unit of measurement, such as '200px' or '2.5em'. By default, the width is set to '100px'. |
| **align**?: string    | This option determines the alignment of the text within the cells of the column. It should be provided as a string with a valid entry. The available options are 'left', 'right', 'center', and 'justify'. By default, the alignment is set to 'left'. |
| **render**?: function | render(cell, x, y, value, instance) => void<br> | This option allows you to override the default rendering of the column and instead render a specific value. It is particularly useful for rendering HTML elements or components. In the context of this property, the keyword 'self' refers to the current row being rendered. |

### Instance

| Property | Description |
| --- | --- |
| data: object[] | Change the state of data. |
| page: Number | Change the page index. |
| pagination: Number | Enable pagination. |
| search: Boolean | Enable search. |
| sort: Function(sortBy: String, sortAsc: Boolean) | Sort the data. |
| setValue: Function(x: Number | String, y: Number, value: String) | Set the value of a cell. |

### Events

| Event | Description |
| --- | --- |
| onsearch?: (self) => void | Called when a search happens. |
| onchangepage?: (self) => void | Called when the user changes the page. |
| onupdate?: (self, object) => void | Called when cell data is changed. |

### Usage

There are two ways to instantiate a Data Grid, Programmatically or Dynamically

#### Programmatically

Create an instance of the data grid by providing the DOM element, and the **_options_** object.

```html
<div id="root"></div>
<script>
    const root = document.getElementById('root')
    Datagrid(root, {
        data: [
            { id: 1, person: 'Maria', age: 28 },
            { id: 2, person: 'Carlos', age: 33 }
        ],
        columns: [
            { name: 'person', title: 'Name' },
            { name: 'age', title: 'Age' }
        ]
    })
</script>
```

#### Dynamically with LemonadeJS

The LemonadeJS data grid is invoked within the template, with the options being passed as properties.

```javascript
import Datagrid from '@lemonadejs/data-grid'
import '@lemonadejs/data-grid/dist/style.css';

export default function Component() {
    let self = this;

    self.data = [
        { id: 1, person: 'Maria', age: 28 },
        { id: 2, person: 'Carlos', age: 33 }
    ]

    self.columns = [
        { name: 'person', title: 'Name' },
        { name: 'age', title: 'Age' }
    ]

    return `<Datagrid :data="self.data" :columns="self.columns" />`
}
```

#### Using in React

```jsx
import React, { useRef } from 'react';
import Datagrid from '@lemonadejs/data-grid/dist/react';
import '@lemonadejs/data-grid/dist/style.css';

const data = [
    { id: 1, person: 'Maria', age: 28 },
    { id: 2, person: 'Carlos', age: 33 }
]

const columns = [
    { name: 'person', title: 'Name' },
    { name: 'age', title: 'Age' }
]
export default function App() {
    const datagrid = useRef();

    return (
        <div>
            <Datagrid data={data} colums={columns} ref={datagrid} />
        </div>);
}
```

Quick example with Vue

```vue
<template>
    <div>
        <Datagrid :data="data" :columns="columns"/>
    </div>
</template>

<script>
import Datagrid from '@lemonadejs/data-grid/dist/vue';
import '@lemonadejs/data-grid/dist/style.css';
export default {
    name: 'App',
    components: {
        Datagrid
    },
    data() {
        return {
            data: [
                { id: 1, person: 'Maria', age: 28 },
                { id: 2, person: 'Carlos', age: 33 }
            ],
            columns: [
                { name: 'person', title: 'Name' },
                { name: 'age', title: 'Age' }
            ]
        };   
    }
}
</script>
```

### Configuration

Additionally, you have the option of incorporating **_pagination_** and **_search_** functionalities by including them in the options. For example:

```javascript
Datagrid(root, {
    data: [
        { id: 1, person: 'Maria', age: 28 },
        { id: 2, person: 'Carlos', age: 33 }
    ],
    columns: [
        { name: 'person', title: 'Name' },
        { name: 'age', title: 'Age' }
    ],
    pagination: 5, // Each page will contain this quantity of items.
    search: true
})
```

### Examples

Here are a few examples of DataGridLM in action:

-   [Basic Data Grid Example](https://lemonadejs.net/components/data-grid#example-1)
-   [Example with Large Data Sets](https://lemonadejs.net/components/data-grid#example-2)
-   [Example with Data Addition and Deletion](https://lemonadejs.net/components/data-grid#example-3)

<br>

## License

The LemonadeJS data grid is released under the MIT.

## Other Tools

-   [jSuites](https://jsuites.net/docs)
-   [Jspreadsheet](https://jspreadsheet.com)