KViews

A modern, class-based JavaScript library for binding JSON API data to DOM elements. KViews provides a clean, declarative way to work with REST APIs and render data using Handlebars templates.

Features

✅ Class-based architecture - Modern ES6 classes for better organization
✅ JSON API support - Full JSON API specification support
✅ Template rendering - Handlebars template support for flexible rendering
✅ Event system - Comprehensive event handling for reactivity
✅ jQuery required - Uses jQuery exclusively for DOM manipulation
✅ Filtering - Built-in form filtering support
✅ CRUD operations - Create, Read, Update, Delete support
✅ Bundle & ES6 modules - Use as bundle or ES6 modules
✅ TypeScript ready - Written in modern JavaScript

Installation

Using Bundle (No Build Step Required)

Download dist/kviews.js and include it in your HTML:

<script src="https://cdn.jsdelivr.net/npm/handlebars@latest/dist/handlebars.min.js"></script>
<script src="./dist/kviews.js"></script>

Using ES6 Modules

npm install kviews

Or copy the src/ directory to your project.

Requirements

Handlebars (required) - For template compilation
jQuery (required) - For DOM manipulation
Modern Browser - ES6 support (Chrome 61+, Firefox 60+, Safari 11+, Edge 16+)

Quick Start

Bundle Version

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.jsdelivr.net/npm/handlebars@latest/dist/handlebars.min.js"></script>
    <script src="./dist/kviews.js"></script>
</head>
<body>
    <div id="posts">
        <div class="post">
            <h2>{{title}}</h2>
            <p>{{content}}</p>
        </div>
    </div>

    <script>
        KViews.createCollectionInstance('#posts', {
            url: '/api/posts',
            type: 'posts'
        });
    </script>
</body>
</html>

ES6 Modules

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.jsdelivr.net/npm/handlebars@latest/dist/handlebars.min.js"></script>
</head>
<body>
    <div id="posts">
        <div class="post">
            <h2>{{title}}</h2>
            <p>{{content}}</p>
        </div>
    </div>

    <script type="module">
        import { KViews } from './src/index.js';
        
        KViews.createCollectionInstance('#posts', {
            url: '/api/posts',
            type: 'posts'
        });
    </script>
</body>
</html>

Usage Examples

Collections

// Create a collection
const collection = KViews.createCollectionInstance('#posts', {
    url: '/api/posts',
    type: 'posts',
    pageSize: 20
});

// Listen to events
collection.on('load', (collection) => {
    log('Loaded', collection.items.length, 'items');
});

// Add new item
collection.append({
    attributes: {
        title: 'New Post',
        content: 'Post content'
    }
});

Items

// Create an item
const item = KViews.createItemInstance('#post-detail', {
    url: '/api/posts/1',
    type: 'posts'
});

// Update item
item.update({
    attributes: {
        title: 'Updated Title'
    }
});

// Delete item
item.delete();

Form Integration

// Fill form with item data
KViews.helpers.fillForm('#edit-form', item);

// Capture form submission
KViews.helpers.captureFormSubmit('#create-form', (formData) => {
    collection.append({ attributes: formData });
});

Filtering

const collection = KViews.createCollectionInstance('#posts', {
    url: '/api/posts',
    type: 'posts',
    filter: '#filter-form'  // Form element for filtering
});

API Overview

KViews (Factory Class)

KViews.createCollectionInstance(el, opts) - Create collection instance
KViews.createItemInstance(el, opts, data) - Create item instance
KViews.baseUrl - Base URL for all API requests
KViews.helpers - Utility functions (fillForm, captureFormSubmit, fetchFormData)

Collection

loadFromRemote() - Load data from API
append(itemData) - Add new item
render() - Render collection
on(event, callback) - Event listeners
items - Array of Item instances

Item

loadFromRemote() - Load item from API
update(data) - Update item
delete() - Delete item
render() - Render item
on(event, callback) - Event listeners

Documentation

Comprehensive documentation is available in the docs/ directory:

API Reference - Complete API documentation
User Guides - Step-by-step guides
Examples - Code examples

Development

Setup

# Clone repository
git clone <repository-url>
cd kviews.js

# Install dependencies
npm install

Build

# Build bundle (normal + minified)
npm run build

This creates:

dist/kviews.js - Normal bundle with sourcemap
dist/kviews.min.js - Minified bundle

Testing

# Run unit tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run E2E tests
npm run test:e2e

# Run all tests
npm run test:all

Development Server

# Python
npm run serve:python

# PHP
npm run serve:php

# Node.js
npm run serve:node

Project Structure

kviews.js/
├── src/                  # Source code
│   ├── KViews.js        # Main factory class
│   ├── Item.js          # Item class
│   ├── Collection.js     # Collection class
│   ├── Storage.js        # HTTP operations
│   ├── URL.js            # URL parsing
│   ├── utilities.js      # Utility functions
│   └── ...
├── dist/                 # Built bundles
├── docs/                 # Documentation
│   ├── api/             # API reference
│   ├── guides/          # User guides
│   └── examples/        # Code examples
├── tests/                # Test suite
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   └── e2e/             # End-to-end tests
└── build.js             # Build script

Browser Support

Chrome 61+
Firefox 60+
Safari 11+
Edge 16+
IE11+ (with polyfills for bundle version)

JSON API Format

KViews expects data in JSON API format:

{
  "data": {
    "id": "1",
    "type": "posts",
    "attributes": {
      "title": "Post Title",
      "content": "Post content"
    },
    "relationships": {
      "author": {
        "data": {
          "id": "123",
          "type": "users"
        }
      }
    }
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Development Guidelines

Follow existing code style
Add tests for new features
Update documentation as needed
Ensure all tests pass

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

Version 2.0.0 (Breaking Changes)

Event System Refactoring:

✅ Unified event system - Removed dual callback system (onafterrender, onbeforeload properties)
✅ New event methods - Added off(), once(), emit(), hasListeners() methods
✅ Standardized events - All events now use on() method exclusively
✅ New Item events - Added beforeload, load, afterrender events (previously missing or inconsistent)
✅ Collection events - Added beforeload event
✅ Return value consistency - Collection.onupdate() now returns this for chaining

Breaking Changes:

❌ Removed: collection.onafterrender and collection.onbeforeload properties
❌ Removed: item.onafterrender property
✅ Migration: Use collection.on('afterrender', callback) instead of collection.onafterrender = callback
✅ Migration: Use collection.on('beforeload', callback) instead of collection.onbeforeload = callback

Improvements:

Event listeners can now be removed with off()
One-time listeners supported with once()
Manual event triggering with emit()
Consistent event API across Collection and Item classes

Version 1.0.3

Fixed bundle to properly expose KViews.createCollectionInstance and KViews.createItemInstance
Refactored Paging to ES6 class
Templates now expose attributes directly (use {{title}} instead of {{attributes.title}})
Utilities exposed via KViews.helpers (recommended access method)
Removed getUtilities() instance methods
Storage class now uses Fetch API exclusively (no jQuery dependency)
Added comprehensive test suite (Vitest + Playwright)
Improved build script to generate both normal and minified bundles

Version 1.0.0

Initial release
Class-based architecture
JSON API support
Handlebars templating
Event system
Form utilities
Bundle and ES6 module support

Support

For issues, questions, or contributions:

Open an issue on GitHub
Check the documentation
Review examples

Acknowledgments

Built with modern JavaScript (ES6+)
Uses Handlebars for templating
Inspired by modern data-binding patterns

Made with ❤️ for modern web development

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
dist		dist
docs		docs
src		src
tests		tests
.gitignore		.gitignore
KVIEWS_AI_DOCUMENTATION.md		KVIEWS_AI_DOCUMENTATION.md
KVIEWS_COMPLETE_DOCUMENTATION.md		KVIEWS_COMPLETE_DOCUMENTATION.md
LICENSE		LICENSE
PARSER_REFACTORING_SUMMARY.md		PARSER_REFACTORING_SUMMARY.md
README.md		README.md
REFACTORING_PASS2_PLAN.md		REFACTORING_PASS2_PLAN.md
REFACTORING_PASS2_SUMMARY.md		REFACTORING_PASS2_SUMMARY.md
REFACTORING_PLAN.md		REFACTORING_PLAN.md
REFACTORING_SUMMARY.md		REFACTORING_SUMMARY.md
apiator.js		apiator.js
build.js		build.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.js		playwright.config.js
vitest.config.js		vitest.config.js

Folders and files

Latest commit

History

Repository files navigation

KViews

Features

Installation

Using Bundle (No Build Step Required)

Using ES6 Modules

Requirements

Quick Start

Bundle Version

ES6 Modules

Usage Examples

Collections

Items

Form Integration

Filtering

API Overview

KViews (Factory Class)

Collection

Item

Documentation

Development

Setup

Build

Testing

Development Server

Project Structure

Browser Support

JSON API Format

Contributing

Development Guidelines

License

Changelog

Version 2.0.0 (Breaking Changes)

Version 1.0.3

Version 1.0.0

Support

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages