LiveDomJS - Dokumentasi Lengkap

Pengenalan LiveDomJS

LiveDomJS adalah library JavaScript modern yang dibangun di atas jQuery untuk membangun aplikasi web interaktif dengan pendekatan deklaratif menggunakan atribut HTML.

LiveDomJS dirancang untuk developer yang ingin membangun aplikasi interaktif tanpa kompleksitas framework modern seperti React/Vue, namun tetap membutuhkan fitur-fitur canggih seperti binding data, animasi, dan SPA routing.

Fitur Utama

Event Handler Deklaratif - Kontrol logika aplikasi langsung dari HTML
Data Binding Otomatis - Sinkronisasi data antara JavaScript dan DOM
Sistem Animasi Built-in - 15+ jenis animasi siap pakai
SPA Router - Navigasi halaman tanpa reload
Komputasi Real-time - Kalkulasi otomatis saat data berubah
Error Handling Canggih - Tampilan error Laravel yang informatif

Instalasi

Via Composer (Laravel)

Jika menggunakan Laravel, instalasi LiveDomJs dapat dilakukan langsung melalui Packagist:

composer require gadingrengga/livedomjs

Setelah itu jalankan perintah instalasi untuk publish asset dan route:

php artisan livedomjs:install

Penggunaan di Blade

Tambahkan script berikut ke dalam layout Blade Anda setelah jQuery:

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
                <script src="{{ asset('vendor/livedomjs/livedom.js') }}"></script>

Konsep Dasar

LiveDomJS bekerja dengan mendefinisikan perilaku aplikasi melalui atribut HTML khusus. Berikut konsep intinya:

1. Live Scope

Setiap komponen harus dibungkus dalam elemen dengan atribut live-scope yang berisi nama controller:

<div live-scope="ProductController">
    <!-- Konten komponen -->
</div>

2. Event Handler

Tangani event dengan atribut seperti live-click, live-change, dll:

<button live-click="updateData">Update</button>

3. Data Binding

Binding data otomatis antara JavaScript dan DOM:

<input type="text" live-model="namaProduk">
<span live-bind="namaProduk"></span>

Event Handler

LiveDomJS menyediakan berbagai event handler deklaratif:

Atribut	Event	Contoh
live-click	Klik mouse	`<button live-click="save">`
live-change	Perubahan nilai input	`<select live-change="filter">`
live-input	Input realtime (dengan debounce)	`<input live-input="search">`
live-submit	Form submit	`<form live-submit="process">`
live-hover	Mouse hover	`<div live-hover="showTooltip">`

Contoh Lengkap

<div live-scope="UserController">
    <input type="text" live-model="username" placeholder="Username">
    
    <select live-change="updateRole" live-model="role">
        <option value="admin">Admin</option>
        <option value="user">User</option>
    </select>
    
    <button live-click="saveUser" class="bg-blue-500 text-white px-4 py-2 rounded">
        Simpan
    </button>
</div>

Semua event handler otomatis terhubung ke method controller dengan nama yang sama. Misal live-click="save" akan memanggil method save() di controller.

Data Binding

LiveDomJS menyediakan beberapa cara untuk binding data antara JavaScript dan DOM:

1. Two-way Binding (live-model)

Sinkronisasi dua arah antara input dan variabel:

<div live-scope="FormController">
    <input type="text" live-model="nama" placeholder="Nama lengkap">
    <p>Halo, <span live-bind="nama"></span>!</p>
</div>

2. One-way Binding (live-bind)

Hanya menampilkan nilai dari variabel:

<div live-scope="ProductController">
    <span live-bind="harga"></span>
</div>

3. Auto Binding dari Response

Otomatis binding data dari respons AJAX:

// Response dari server
{
    "success": true,
    "data": {
        "namaProduk": "Laptop Gaming",
        "harga": 15000000,
        "stok": 10
    }
}

<div live-scope="ProductController">
    <h3 live-bind="namaProduk"></h3>
    <p live-bind="harga" live-compute-format="currency"></p>
    <p live-bind="stok"></p>
</div>

LiveDomJS akan otomatis mencocokkan key dari response JSON dengan atribut live-bind di DOM. Jika key tidak ditemukan, elemen tidak akan diupdate.

Sistem Animasi

LiveDomJS memiliki sistem animasi built-in yang bisa diakses melalui atribut live-animate:

Fade

fade-in
fade-out
fade-toggle

Slide

slide-up
slide-down
slide-left
slide-right
slide-toggle

Zoom

zoom-in
zoom-out
zoom-toggle

Scale

scale-up
scale-down
scale-toggle

Contoh Penggunaan

<!-- Animasi dasar -->
<button live-click="togglePanel" live-target="#panel" live-animate="fade-toggle">
    Toggle Panel
</button>

<!-- Animasi dengan pengaturan khusus -->
<div id="panel" live-animate="slide-down" live-duration="500" live-easing="ease-out">
    Konten panel...
</div>

Atribut Pendukung

live-duration: Durasi animasi dalam milidetik (default: 300)
live-easing: Fungsi easing (default: 'swing')
live-target: Target elemen untuk animasi (default: elemen itu sendiri)

Untuk animasi custom, Anda bisa menggunakan nama class CSS sebagai nilai live-animate. LiveDomJS akan otomatis menambahkan dan menghapus class tersebut sesuai durasi yang ditentukan.

SPA Router

LiveDomJS memiliki sistem routing SPA (Single Page Application) built-in yang memungkinkan navigasi antar halaman tanpa reload browser.

1. Setup Dasar

<body>
    <!-- Header tetap -->
    <header>...</header>
    
    <!-- Region konten dinamis -->
    <main live-spa-region="main">
        <!-- Konten akan diupdate via AJAX -->
    </main>
    
    <!-- Footer tetap -->
    <footer>...</footer>
</body>

2. Navigasi SPA

Semua link dalam live-spa-region otomatis menjadi SPA links:

<nav>
    <a href="/dashboard">Dashboard</a>
    <a href="/products">Produk</a>
    <a href="/contact">Kontak</a>
</nav>

3. Form Handling

Form dalam SPA region otomatis dihandle via AJAX:

<form method="POST" action="/contact">
    <input type="text" name="name">
    <button type="submit">Kirim</button>
</form>

Untuk mengecualikan URL tertentu dari SPA (misal link ke halaman luar), tambahkan atribut data-spa-exclude atau konfigurasi global di window.liveDomConfig.spaExcludePrefixes.

Komputasi Real-time

Fitur live-compute memungkinkan kalkulasi otomatis saat data berubah:

1. Ekspresi Dasar

<div live-scope="OrderController">
    <input type="number" live-model="quantity">
    <input type="number" live-model="price">
    
    <p>Total: <span live-compute="quantity * price"></span></p>
</div>

2. Fungsi Agregasi

Khusus untuk data tabel dengan struktur array:

<table live-scope="OrderController">
    <!-- Baris data -->
    <tr>
        <td><input type="number" name="rows[0][qty]"></td>
        <td><input type="number" name="rows[0][price]"></td>
        <td live-compute="rows_0_qty * rows_0_price"></td>
    </tr>
    
    <!-- Total -->
    <tr>
        <td colspan="2">Grand Total</td>
        <td live-compute="sum('rows[?][price]')"></td>
    </tr>
</table>

3. Format Output

<!-- Format mata uang -->
<span live-compute="total" live-compute-format="currency"></span>

<!-- Format tanggal -->
<span live-compute="days" live-compute-format="hari"></span>

LiveDomJS otomatis mendeteksi perubahan pada input terkait dan menghitung ulang nilai. Untuk tabel dinamis, gunakan pola rows[?][field] dimana ? akan diganti dengan index setiap baris.

Sistem Accordion

LiveDomJS menyediakan sistem accordion khusus untuk tabel/data grid:

1. Basic Usage

<table live-scope="OrderController">
    <tr live-accordion="loadDetails">
        <td>Order #123</td>
        <td>
            <button live-accordion>
                <span class="accordion-icon">▼</span>
            </button>
        </td>
    </tr>
    <!-- Konten accordion akan dimuat via AJAX -->
</table>

2. Custom Target

<div live-scope="ProductController">
    <div live-click="toggleDetails" live-accordion live-target="#product-details">
        Klik untuk detail
    </div>
    
    <div id="product-details" style="display: none;">
        Konten detail produk...
    </div>
</div>

3. Callback & Event

// Callback saat accordion terbuka
document.addEventListener('live-accordion:opened', (e) => {
    console.log('Accordion opened:', e.detail);
});

// Callback saat accordion tertutup
document.addEventListener('live-accordion:closed', (e) => {
    console.log('Accordion closed:', e.detail);
});

Auto Polling

Fitur polling otomatis untuk update data berkala:

1. Basic Polling

<div live-poll="5000" live-click="updateData">
    Data terakhir diupdate: <span live-bind="lastUpdated"></span>
</div>

2. Conditional Polling

<div live-poll="3000" live-poll-when="needsUpdate === true">
    Data akan diupdate setiap 3 detik jika kondisi terpenuhi
</div>

Nilai live-poll adalah interval dalam milidetik. Polling akan berjalan selama elemen tetap ada di DOM dan halaman visible.

Error Handling

LiveDomJS memiliki sistem penanganan error yang canggih untuk menampilkan error dari server:

1. Error Modal Otomatis

Semua error dari server akan ditampilkan dalam modal yang informatif:

2. Validasi Form

<form live-submit="saveData">
    <input type="text" name="email">
    <!-- Pesan error akan muncul di sini -->
</form>

3. Custom Error Handler

// Override default error handler
window.liveDomConfig = {
    onError: function(error) {
        // Custom logic
        console.error('LiveDomJS Error:', error);
    }
};

Kombinasi Fitur

Kekuatan LiveDomJS terletak pada kemampuannya mengkombinasikan berbagai fitur:

1. Form dengan Validasi & Animasi

<form live-scope="ContactController" live-submit="sendMessage" 
      live-animate="fade-in" live-target=".feedback-message">
    
    <input type="text" live-model="name" placeholder="Nama">
    <input type="email" live-model="email" placeholder="Email">
    
    <button live-click="submit" live-action="disable: self; add-class: bg-gray-400">
        Kirim Pesan
    </button>
    
    <div class="feedback-message hidden">
        <p live-bind="feedback"></p>
    </div>
</form>

2. Tabel Interaktif

<table live-scope="ProductController" live-poll="10000">
    <thead>
        <tr>
            <th live-click="sortBy('name')">Nama Produk</th>
            <th live-click="sortBy('price')">Harga</th>
        </tr>
    </thead>
    
    <tbody>
        <tr live-accordion="loadDetail" live-target="next tr">
            <td live-bind="name"></td>
            <td live-compute="price" live-compute-format="currency"></td>
        </tr>
    </tbody>
</table>

3. Dashboard Real-time

<div live-scope="DashboardController">
    <div live-spa-region="stats" live-poll="5000">
        <div class="stat-card" live-animate="fade-in" live-duration="300">
            <h3>Total Pengunjung</h3>
            <p live-bind="visitors"></p>
        </div>
    </div>
    
    <div live-if="visitors > 1000" live-action="show" live-animate="pulse">
        Pencapaian tercapai!
    </div>
</div>