opengridjs

v1.2.1

Published

3 months ago

A lightweight JavaScript grid framework that allows you to create fast and easy-to-use data grids in your web application. It supports virtual scrolling, custom column headers, and context menus.

0High
0Medium
0Low

amurgola

OpenGridJs

A lightweight, high-performance JavaScript grid framework for modern web applications. OpenGridJs delivers fast, responsive data grids with virtual scrolling, advanced column management, and extensive customization options.

✨ Features

Performance & Scalability

Virtual Scrolling: Efficiently handles large datasets by rendering only visible rows
Lightweight: Minimal footprint with no external dependencies
Optimized Rendering: Smart DOM updates for smooth scrolling and interactions

Column Management

Auto-Detection: Automatically generates columns from data structure
Custom Headers: Define custom column names, display names, and formatting
Drag & Drop Reordering: Intuitive column reordering via drag and drop
Resizable Columns: Interactive column resizing with visual feedback
Flexible Widths: Support for both percentage and pixel-based column sizing

Data Handling

Asynchronous Loading: Promise-based data loading with loading states
Infinite Scrolling: Load more data automatically as users scroll
Real-time Updates: Update records by ID with visual animations and position preservation
Dynamic Updates: Append, filter, and refresh data without full re-renders
GUID Generation: Automatic ID assignment for data items without identifiers

User Interactions

Sorting: Click-to-sort columns with visual indicators
Filtering: Built-in search and filter capabilities
Context Menus: Configurable right-click context menus
CSV Export: Export grid data to CSV format
Row Selection: Single and multi-row selection support

Developer Experience

TypeScript Ready: Full TypeScript support with type definitions
Modern Browsers: Compatible with all modern browsers
Easy Integration: Simple API with minimal setup required
Extensible: Flexible configuration and customization options

📦 Installation

NPM

npm install opengridjs

CDN

<link rel="stylesheet" href="https://unpkg.com/opengridjs@latest/opengrid.min.css">
<script src="https://unpkg.com/opengridjs@latest/opengrid.min.js"></script>

Direct Download

Download the latest release from the GitHub releases page.

🚀 Quick Start

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="https://unpkg.com/opengridjs/opengrid.min.css">
    <script src="https://unpkg.com/opengridjs/opengrid.min.js"></script>
</head>
<body>
    <div id="myGrid"></div>
    
    <script>
        // Sample data
        const sampleData = [
            { id: 1, name: "John Doe", email: "[email protected]", age: 30 },
            { id: 2, name: "Jane Smith", email: "[email protected]", age: 25 },
            { id: 3, name: "Bob Johnson", email: "[email protected]", age: 35 }
        ];

        // Initialize grid
        const grid = new OpenGrid("myGrid", sampleData, 400);
    </script>
</body>
</html>

📊 Demo

OpenGridJs Demo

Live Demo on CodePen

🔧 Configuration

Constructor Parameters

new OpenGrid(containerId, data, height, setup, loadMoreFunction)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | containerId | string | ✅ | ID of the container element | | data | Array/Function | ✅ | Initial data or async loading function | | height | number | ✅ | Grid height in pixels | | setup | Object | ❌ | Configuration options | | loadMoreFunction | Function | ❌ | Function for infinite scrolling |

Setup Object

const setup = {
    columnHeaderNames: [
        {
            columnName: "name",
            columnNameDisplay: "Full Name",
            columnWidth: "200px", // Optional: specific width
            format: (value) => value.toUpperCase() // Optional: custom formatter
        }
    ],
    contextMenuTitle: "Actions",
    contextMenuOptions: [
        {
            actionName: "Edit",
            actionFunctionName: "editRow",
            className: "edit-action"
        },
        {
            actionName: "Delete", 
            actionFunctionName: "deleteRow",
            className: "delete-action"
        }
    ]
};

Column Configuration

| Property | Type | Description | |----------|------|-------------| | columnName | string | Data field name | | columnNameDisplay | string | Display name in header | | columnWidth | string | CSS width value (e.g., "200px", "20%") | | format | function | Custom formatting function |

Context Menu Configuration

| Property | Type | Description | |----------|------|-------------| | actionName | string | Display text for menu item | | actionFunctionName | string | Global function name to call | | className | string | CSS class for styling |

🎯 Advanced Usage

Asynchronous Data Loading

async function loadData() {
    const response = await fetch('/api/data');
    return response.json();
}

const grid = new OpenGrid("myGrid", loadData, 400, setup);

Infinite Scrolling

async function loadMoreData() {
    const response = await fetch(`/api/data?page=${currentPage++}`);
    const newData = await response.json();
    grid.appendData(newData);
}

const grid = new OpenGrid("myGrid", loadData, 400, setup, loadMoreData);

Custom Formatting

const setup = {
    columnHeaderNames: [
        {
            columnName: "price",
            columnNameDisplay: "Price",
            format: (value) => `$${value.toFixed(2)}`
        },
        {
            columnName: "date",
            columnNameDisplay: "Created",
            format: (value) => new Date(value).toLocaleDateString()
        },
        {
            columnName: "email",
            columnNameDisplay: "Email",
            format: (value) => `<a href="mailto:${value}">${value}</a>`
        }
    ]
};

🛠️ API Reference

Methods

| Method | Parameters | Description | |--------|------------|-------------| | appendData(data) | Array | Add new data to the grid | | updateRecordData(data, options) | Array/Object, Options | Update records by ID with animations | | rerender() | none | Force grid re-render | | reset() | none | Reset grid to initial state | | exportToCSV() | none | Download grid data as CSV | | searchFilter(term) | string | Filter data by search term | | stopLoadingMoreData() | none | Disable infinite scrolling |

Usage Examples

// Add new data
grid.appendData([
    { id: 4, name: "Alice Brown", email: "[email protected]", age: 28 }
]);

// Real-time updates with animations
// Update single record
grid.updateRecordData({ id: 2, score: 95, status: "Active" });

// Update multiple records
grid.updateRecordData([
    { id: 1, score: 88 },  // Green animation if score increased
    { id: 3, score: 72 }   // Red animation if score decreased
]);

// Update with custom options
grid.updateRecordData(
    { id: 4, name: "John Updated", score: 90 },
    {
        animate: true,           // Enable animations (default: true)
        preservePosition: true,  // Prevent row reordering (default: true)
        highlightDuration: 3000  // Animation duration in ms (default: 2000)
    }
);

// Filter data
grid.searchFilter("john");

// Export to CSV
grid.exportToCSV();

// Reset grid
grid.reset();

🔄 Real-time Updates

OpenGridJs now supports real-time data updates with visual animations and intelligent positioning:

Features

ID-based Updates: Update records by matching their unique ID
Visual Animations:
- 🟢 Green for numeric increases
- 🔴 Red for numeric decreases
- 🔵 Blue for non-numeric changes
Position Preservation: Updates don't cause data bouncing or reordering
Batch Updates: Update multiple records simultaneously
Centered Filter Menus: Filter menus now appear centered under column headers

Animation Types

// Numeric increase (green animation)
grid.updateRecordData({ id: 1, score: 95 }); // if previous score was lower

// Numeric decrease (red animation)
grid.updateRecordData({ id: 1, score: 75 }); // if previous score was higher

// Non-numeric change (blue animation)
grid.updateRecordData({ id: 1, name: "New Name", status: "Updated" });

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | animate | boolean | true | Enable/disable animations | | preservePosition | boolean | true | Prevent row reordering during updates | | highlightDuration | number | 2000 | Animation duration in milliseconds |

Demo

Try the interactive demo at demo-realtime-updates.html to see all features in action!

🎨 Styling & Theming

OpenGridJs provides extensive CSS customization options:

/* Custom theme example */
.opengridjs-grid {
    --primary-color: #007bff;
    --background-color: #ffffff;
    --border-color: #dee2e6;
    --hover-color: #f8f9fa;
    --selected-color: #e3f2fd;
}

.opengridjs-grid-header {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
}

.opengridjs-grid-row:hover {
    background-color: var(--hover-color);
    transform: translateY(-1px);
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

🧪 Testing

OpenGridJs includes comprehensive test coverage:

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

🏗️ Development

# Clone repository
git clone https://github.com/amurgola/OpenGridJs.git
cd OpenGridJs

# Install dependencies
npm install

# Run tests
npm test

# Build minified versions
npm run build

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📋 Browser Support

| Browser | Version | |---------|---------| | Chrome | ≥ 60 | | Firefox | ≥ 55 | | Safari | ≥ 12 | | Edge | ≥ 79 |

📄 License

OpenGridJs is released under the MIT License.

🙏 Acknowledgments

Built with performance and developer experience in mind
Inspired by modern data grid requirements
Community feedback and contributions

Made with ❤️ by the OpenGridJs team