Ngorei - framework

Struktur HTML

Struktur HTML ViewStack menggunakan sistem nested views yang memungkinkan pengorganisasian konten secara hierarkis. Parent view dapat memiliki multiple child views yang diidentifikasi menggunakan data-section.

<!-- Parent View -->
<Viewstack id="parent-id" [true]>
    <h4>Judul Parent</h4>
    
    <!-- Child Views -->
    <div data-section id="child-1">
        <h4>Child 1</h4>
        <!-- konten child 1 -->
    </div>
    
    <div data-section id="child-2">
        <h4>Child 2</h4>
        <!-- konten child 2 -->
    </div>
</Viewstack>

Penjelasan Detail:

Struktur Dasar
- Tag Viewstack sebagai container utama
- Atribut id untuk identifikasi unik
- Atribut true untuk tampilan awal
- data-section untuk child views
- Mendukung nested views hingga beberapa level
- Otomatis menangani visibilitas child views
- Terintegrasi dengan sistem routing
Penggunaan Atribut
- id: Harus unik untuk setiap Viewstack
- true: Mengatur tampilan default saat load
- data-section: Menandai child view sections
- class: Untuk styling tambahan jika diperlukan
Fitur Tambahan
- Mendukung lazy loading konten
- Kompatibel dengan animasi transisi
- Dapat dikustomisasi melalui CSS
- Terintegrasi dengan event system

Struktur Navigasi

Navigasi ViewStack menggunakan sistem URL berbasis hash yang memungkinkan deep-linking dan browser history. Format navigasi mendukung hierarki parent-child untuk kemudahan akses ke berbagai level konten.

<!-- Menu Navigasi -->
<ul class="navigation">
    <!-- Parent Menu -->
    <li><a href="#parent-id">Parent Menu</a>
        <ul>
            <!-- Child Menu -->
            <li><a href="#parent-id/child-1">Child Menu 1</a></li>
            <li><a href="#parent-id/child-2">Child Menu 2</a></li>
        </ul>
    </li>
</ul>

Penjelasan Detail:

Navigasi
- Struktur menu bertingkat
- Format URL dengan hash (#)
- Nested navigation support
- Automatic state tracking

Fitur Utama

ViewStack menyediakan berbagai fitur utama untuk mengelola tampilan dan state aplikasi. Fitur-fitur ini mencakup perilaku tampilan yang konsisten, manajemen state yang handal, dan kemampuan untuk menyimpan state di URL maupun penyimpanan lokal.

Perilaku Tampilan

ViewStack memiliki perilaku tampilan yang intuitif dengan kemampuan menampilkan konten secara dinamis berdasarkan interaksi pengguna. Sistem ini mendukung navigasi bertingkat dan penyimpanan state otomatis.

Perilaku Default
- Klik parent menu: Menampilkan semua child sections
- Klik child menu: Menampilkan hanya section yang dipilih
- State tersimpan di URL (hash) dan IndexedDB
- Mendukung browser back/forward navigation

State Management

Sistem manajemen state ViewStack menyediakan mekanisme untuk melacak dan mempertahankan status tampilan. Informasi state disimpan dalam format yang terstruktur dan dapat diakses melalui API yang disediakan.

// Mendapatkan informasi view aktif
const viewInfo = viewStack.getViewInfo();
console.log(viewInfo);
/* Output:
{
    URL: "parent-id/child-1",
    View: "parent-id",
    Section: "child-1",
    Page: "parent-id",
    Params: "child-1"
}
*/

Penjelasan Detail:

State Management
- Tracking view aktif
- Persistensi state via URL
- History management
- Parameter handling

Event Callbacks

Sistem callback pada ViewStack memungkinkan developer untuk merespon berbagai event yang terjadi selama siklus hidup komponen. Callbacks ini berguna untuk implementasi logika kustom, validasi, logging, dan penanganan error.

beforeViewChange

Event callback yang dipanggil sebelum perubahan view terjadi. Berguna untuk validasi, konfirmasi, atau persiapan data sebelum navigasi dilakukan. Dapat mencegah navigasi dengan mengembalikan nilai false.

const viewStack = new ViewStack({
    beforeViewChange: (parentId, childId) => {
        console.log(`Navigating to $${childId ? '/' + childId : ''}`);
        // Return false to prevent navigation
        return true;
    }
});

Penjelasan:

Dipanggil sebelum view berubah
Dapat mencegah navigasi dengan return false
Menerima parentId dan childId sebagai parameter

afterViewChange

Callback yang dieksekusi setelah perubahan view selesai. Ideal untuk menginisialisasi komponen, memuat data, atau melakukan tracking setelah navigasi berhasil dilakukan.

const viewStack = new ViewStack({
    afterViewChange: (parentId, childId, view) => {
        console.log(`Navigated to $${childId ? '/' + childId : ''}`);
        // Akses element view yang aktif
        console.log(view);
    }
});

onViewNotFound

Handler untuk menangani kasus ketika view yang diminta tidak ditemukan. Memungkinkan implementasi fallback view atau pesan error yang sesuai dengan kebutuhan aplikasi.

const viewStack = new ViewStack({
    onViewNotFound: (targetId) => {
        console.warn(`View tidak ditemukan: $`);
        // Handle view not found error
    }
});

onNavigate

Event yang dipicu saat navigasi terjadi, baik melalui interaksi pengguna maupun programatik. Berguna untuk tracking, logging, atau sinkronisasi dengan komponen lain dalam aplikasi.

const viewStack = new ViewStack({
    onNavigate: (targetId) => {
        console.log(`Navigation occurred: $`);
        // Track navigation events
    }
});

Callback	Parameter	Deskripsi
beforeViewChange	(parentId, childId)	Dipanggil sebelum view berubah
afterViewChange	(parentId, childId, view)	Dipanggil setelah view berubah
onViewNotFound	(targetId)	Dipanggil jika view tidak ditemukan
onNavigate	(targetId)	Dipanggil saat navigasi terjadi

Best Practices

Mengikuti best practices dalam penggunaan ViewStack akan membantu menciptakan kode yang lebih maintainable dan menghindari masalah umum dalam pengembangan. Bagian ini mencakup panduan untuk penamaan, strukturisasi, dan penanganan error.

Penamaan dan Struktur
- Gunakan ID yang unik dan deskriptif
- Struktur HTML yang konsisten (Viewstack > data-section)
- Implementasikan error handling melalui callbacks
- Manfaatkan state management untuk persistensi data

Implementasi

Contoh implementasi lengkap ViewStack dalam skenario nyata. Bagian ini mendemonstrasikan penggunaan ViewStack untuk manajemen database, termasuk navigasi antar halaman konfigurasi dan manajemen tabel.

<!-- HTML -->
<ul class="navigation">
    <li>
        <a href="#database">Database</a>
        <ul>
            <li><a href="#database/config">Konfigurasi</a></li>
            <li><a href="#database/tables">Tabel</a></li>
        </ul>
    </li>
</ul>

<Viewstack id="database" true>
    <h4>Database Management</h4>
    
    <div data-section id="config">
        <h4>Konfigurasi Database</h4>
        <!-- konten konfigurasi -->
    </div>
    
    <div data-section id="tables">
        <h4>Manajemen Tabel</h4>
        <!-- konten tabel -->
    </div>
</Viewstack>