AI Chat Widget

TM AI Chat Widget

Fitur TM AI Chat Widget menyediakan cara yang powerful untuk membuat komponen visual interaktif yang dapat di-render secara dinamis dalam percakapan AI Chat. Widget ini memungkinkan AI agent untuk menyajikan data, visualisasi, dan konten interaktif kepada pengguna dalam format yang terstruktur dan menarik secara visual.

Memahami DocType TM AI Chat Widget

Tujuan: TM AI Chat Widget memungkinkan developer untuk membuat komponen UI yang dapat digunakan kembali dan dapat dipanggil oleh AI agent selama percakapan. Widget ini mengubah data mentah menjadi presentasi visual yang kaya, seperti chart, preview dokumen, tabel data, atau interface HTML khusus. Ini menjembatani kesenjangan antara conversational AI dan representasi data visual.

Fungsi: DocType ini memungkinkan Anda untuk mendefinisikan template HTML (dengan dukungan Jinja2), styling CSS, dan skema JSON yang menentukan data apa yang diharapkan oleh widget. Ketika AI agent menentukan bahwa widget harus ditampilkan, agent menghasilkan data yang diperlukan sesuai dengan skema, dan widget di-render secara real-time dalam interface chat. Widget diisolasi menggunakan Shadow DOM untuk mencegah konflik style dan mendukung fitur advanced seperti integrasi Frappe Charts.

Role yang Diperlukan

  • System Manager - Akses penuh untuk create, read, update, delete, dan mengelola dokumen TM AI Chat Widget

Field TM AI Chat Widget

Field Deskripsi
Name Identifier unik untuk widget (misalnya, "chart", "document_preview"). Nama ini digunakan oleh AI agent untuk mereferensikan dan memanggil widget.
Description Deskripsi yang jelas tentang apa yang dilakukan widget dan kapan harus digunakan. Deskripsi ini diberikan kepada AI agent untuk membantu mereka menentukan kapan harus menggunakan widget ini. Harus detail dan spesifik.
Application Menghubungkan widget ke My Application tertentu. Field ini wajib untuk custom widget dan tidak dapat diubah setelah dibuat. System-generated widget tidak memerlukan ini.
System Generated Checkbox yang menunjukkan apakah widget ini adalah bagian dari core system (dicentang) atau custom widget yang dibuat oleh pengguna (tidak dicentang). System widget tidak dapat dimodifikasi.
Input Schema (JSON) Definisi JSON Schema yang menentukan struktur dan tipe data yang diharapkan oleh widget. Harus berupa JSON yang valid. Schema ini memberi tahu AI agent data apa yang harus disediakan saat memanggil widget. Termasuk properties, types, required fields, dan validation rules.
Preview Sample Data (JSON) Payload JSON opsional yang digunakan untuk testing dan preview widget di form. Harus sesuai dengan struktur Input Schema. Membantu developer menguji rendering widget tanpa perlu memicu dari percakapan AI.
Template HTML Template HTML dengan dukungan syntax Jinja2. Mendefinisikan struktur visual widget. Dapat mengakses semua data yang dikirim melalui Input Schema. Mendukung loop, conditional, filter, dan fitur Jinja2 lainnya. Field wajib.
CSS Custom CSS styling untuk widget. Diterapkan dalam boundary Shadow DOM untuk mencegah konflik dengan style aplikasi utama. Dapat menggunakan CSS variables untuk kompatibilitas tema. Field opsional.

Prosedur

1. Navigate ke TechMaju AI Module > TM AI Chat Widget

Akses daftar widget dari modul TechMaju AI di workspace Anda atau langsung navigate ke /app/tm-ai-chat-widget.

2. Menambahkan TM AI Chat Widget Baru

Langkah 2.1: Klik '+ Add TM AI Chat Widget'

Ini membuka form pembuatan widget.

Langkah 2.2: Isi Informasi Umum

  • Name: Masukkan nama unik dan deskriptif untuk widget Anda (misalnya, "saleschart", "customercard", "task_list")
  • Description: Tulis deskripsi detail yang menjelaskan:
    • Apa yang ditampilkan widget
    • Kapan harus digunakan
    • Data apa yang divisualisasikan
    • Contoh: "Menghasilkan visualisasi data interaktif (Line, Bar, Pie, Percentage, Heatmap) untuk menampilkan tren, perbandingan, atau distribusi. Gunakan widget ini ketika pengguna meminta 'chart', 'graph', 'visual', atau ingin menganalisis tren data numerik dari waktu ke waktu atau berdasarkan kategori."
  • Application: Pilih My Application yang menjadi tempat widget ini (untuk custom widget)
  • System Generated: Biarkan tidak dicentang (hanya system widget yang harus dicentang)

3. Mengkonfigurasi Schema Widget

Langkah 3.1: Definisikan Input Schema (JSON)

Buat JSON Schema yang mendefinisikan data apa yang dibutuhkan widget Anda:

{
  "type": "object",
  "required": ["title", "data"],
  "properties": {
    "title": {
      "type": "string",
      "description": "Judul yang ditampilkan di atas chart"
    },
    "data": {
      "type": "object",
      "description": "Konfigurasi data chart",
      "properties": {
        "labels": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Label sumbu X"
        },
        "datasets": {
          "type": "array",
          "description": "Data series yang akan diplot"
        }
      }
    },
    "chartType": {
      "type": "string",
      "enum": ["line", "bar", "pie", "percentage"],
      "default": "line",
      "description": "Jenis chart yang akan di-render"
    }
  }
}

Best Practice untuk Schema: - Gunakan nama property yang deskriptif - Sertakan deskripsi detail untuk setiap field - Tentukan field yang required vs. optional - Gunakan enum untuk set nilai yang terbatas - Tambahkan nilai default jika sesuai - Buat schema sesederhana mungkin sambil memenuhi kebutuhan

Langkah 3.2: Buat Preview Sample Data (Opsional)

Berikan sample data yang sesuai dengan schema Anda untuk testing:

{
  "title": "Performa Penjualan Bulanan",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr", "Mei"],
    "datasets": [
      {
        "name": "Pendapatan",
        "values": [12000, 15000, 18000, 16000, 21000]
      }
    ]
  },
  "chartType": "line"
}

4. Mendesain Template Widget

Langkah 4.1: Tulis Template HTML

Buat template HTML Anda menggunakan syntax Jinja2. Anda memiliki akses ke semua properties yang didefinisikan di Input Schema:

<div class="widget-container">
    <h3 class="widget-title">{{ title }}</h3>

    {% if chartType == "line" %}
    <div class="chart-wrapper" data-chart-type="line">
        <div id="chart" data-labels='{{ data.labels | tojson }}' 
             data-datasets='{{ data.datasets | tojson }}'></div>
    </div>
    {% endif %}

    {% if data.datasets %}
    <div class="data-summary">
        <p>Total dataset: {{ data.datasets | length }}</p>
    </div>
    {% endif %}
</div>

Fitur Template: - Dukungan penuh Jinja2 (loop, conditional, filter) - Akses ke semua properties schema - Dapat menggunakan Jinja2 filter seperti tojson, default, length - Dukungan untuk struktur data yang kompleks

Untuk Chart Widget: - Gunakan attribute data-chart-type untuk menentukan jenis chart - Tandai chart dengan isChart: true di data - Chart secara otomatis diinisialisasi menggunakan library Frappe Charts

Langkah 4.2: Tambahkan Custom CSS Styling

Definisikan style untuk widget Anda. Ingat bahwa style ini di-scope ke Shadow DOM:

.widget-container {
    padding: 1.5rem;
    background: var(--card-bg);
    border-radius: 8px;
    border: 1px solid var(--border-color);
}

.widget-title {
    font-size: 1.25rem;
    font-weight: 600;
    margin-bottom: 1rem;
    color: var(--text-color);
}

.chart-wrapper {
    min-height: 300px;
    margin: 1rem 0;
}

.data-summary {
    margin-top: 1rem;
    padding-top: 1rem;
    border-top: 1px solid var(--border-color);
    font-size: 0.875rem;
    color: var(--text-muted);
}

Best Practice CSS: - Gunakan CSS custom properties (variables) untuk kompatibilitas tema - Variable umum: --card-bg, --border-color, --text-color, --text-muted, --primary-color - Hindari positioning absolute yang mungkin rusak di context yang berbeda - Test di tema light dan dark - Jaga specificity tetap rendah untuk memudahkan override

5. Testing dan Preview Widget

Langkah 5.1: Simpan Widget

Klik tombol Save untuk menyimpan konfigurasi widget Anda.

Langkah 5.2: Gunakan Fitur Preview

  • Klik tombol Preview di toolbar
  • Ini membuka dialog yang menampilkan widget Anda di-render dengan Preview Sample Data
  • Preview menggunakan rendering engine yang sama dengan interface chat live
  • Periksa untuk:
    • Rendering data yang benar
    • Styling yang tepat
    • Tidak ada JavaScript error di console
    • Layout yang responsive
    • Inisialisasi chart (jika applicable)

Langkah 5.3: Iterasi dan Perbaiki

  • Lakukan penyesuaian pada template, CSS, atau schema sesuai kebutuhan
  • Simpan dan preview lagi
  • Ulangi sampai puas dengan output

6. Integrasi dengan AI Chat Agent

Langkah 6.1: Hubungkan Widget ke AI Agent

  • Navigate ke TM AI Chat Agent yang ingin Anda aktifkan widget ini
  • Di child table Widgets, tambahkan row baru
  • Pilih widget yang baru Anda buat dari dropdown
  • Simpan agent

Langkah 6.2: Cara AI Agent Menggunakan Widget

Ketika pesan pengguna mengindikasikan bahwa output visual akan berguna, AI agent: 1. Menentukan widget mana yang paling sesuai berdasarkan deskripsi widget 2. Menghasilkan data yang sesuai dengan Input Schema widget 3. Memanggil widget sebagai "tool" dengan data yang dihasilkan 4. Sistem me-render template widget dengan data yang disediakan 5. Widget yang di-render muncul di interface chat

Contoh Flow:

User: "Tunjukkan chart penjualan 5 bulan terakhir"
  ↓
Agent menganalisis request dan menentukan widget "chart" sesuai
  ↓
Agent menghasilkan data sesuai schema widget chart
  ↓
Sistem me-render widget chart dengan data
  ↓
User melihat chart interaktif di interface chat

7. Fitur Advanced

Langkah 7.1: Multiple Widget Per Pesan

AI agent dapat me-render beberapa widget dalam satu response. Setiap widget muncul sebagai blok terpisah dalam percakapan.

Langkah 7.2: Validasi Data Widget

Sistem secara otomatis memvalidasi bahwa data yang disediakan oleh AI agent sesuai dengan Input Schema. Data yang invalid akan menghasilkan error rendering.

Langkah 7.3: Fitur Khusus Chart

Untuk chart widget: - Set isChart: true di object data - Gunakan attribute data-chart-type pada container chart - Tipe chart yang didukung: line, bar, pie, percentage, heatmap - Chart bersifat interaktif dengan hover tooltip - Secara otomatis di-style sesuai tema

Best Practice

Prinsip Desain Widget

  1. Single Responsibility: Setiap widget harus melakukan satu hal dengan baik. Buat widget terpisah untuk jenis visualisasi yang berbeda daripada satu widget multi-purpose yang kompleks.

  2. Deskripsi yang Jelas: Tulis deskripsi widget yang dengan jelas menjelaskan:

    • Data apa yang ditampilkan widget
    • Kapan menggunakannya vs. widget serupa lainnya
    • Keyword yang harus memicu penggunaannya
    • Contoh use case

  3. Kesederhanaan Schema: Buat Input Schema sesederhana mungkin. Struktur nested yang kompleks meningkatkan kemungkinan AI agent menghasilkan data yang invalid.

  4. Error Handling di Template: Gunakan pengecekan conditional Jinja2 untuk menangani data yang hilang atau invalid dengan baik:

    {% if data %}
    <!-- render data -->
{% else %}
    <p>Tidak ada data yang tersedia</p>
{% endif %}

  5. Desain Responsive: Pastikan widget bekerja di berbagai ukuran layar. Gunakan unit relatif (%, rem) daripada pixel tetap jika memungkinkan.

Optimisasi Performa

  1. Efisiensi Template: Hindari komputasi kompleks di template. Proses data terlebih dahulu di AI agent jika memungkinkan.

  2. Efisiensi CSS: Gunakan selector yang efisien dan hindari nesting yang dalam. Shadow DOM sudah menyediakan isolasi.

  3. Ukuran Data: Jaga payload data tetap wajar. Dataset yang sangat besar harus dipaginasi atau diringkas.

  4. Performa Chart: Untuk chart dengan banyak data point, pertimbangkan untuk mengagregasi atau sampling data sebelum visualisasi.

Pertimbangan Keamanan

  1. Sanitasi Data: Jangan pernah gunakan filter | safe pada data yang disediakan pengguna di template kecuali benar-benar diperlukan dan data sudah disanitasi.

  2. Kontrol Akses: Widget mewarisi permission context dari AI Chat Agent. Data sensitif hanya boleh disertakan dalam widget yang dilampirkan ke agent yang dibatasi.

  3. Testing: Selalu test widget dengan berbagai input data untuk memastikan mereka menangani edge case dengan baik.

Maintenance dan Versioning

  1. Dokumentasi: Dokumentasikan setiap requirement atau behavior khusus di deskripsi widget.

  2. Backward Compatibility: Saat mengupdate widget yang ada, pastikan perubahan tidak merusak AI agent yang sudah menggunakannya.

  3. Testing Setelah Update: Setelah memodifikasi widget, test dengan semua AI agent yang menggunakannya.

  4. Konvensi Penamaan: Gunakan penamaan yang jelas dan konsisten untuk widget (misalnya, pola verbnoun: "showchart", "display_table").

Best Practice Integrasi

  1. Progressive Enhancement: Desain widget agar tetap bekerja bahkan jika beberapa field data opsional hilang.

  2. User Feedback: Sertakan loading state dan error message di template Anda jika sesuai.

  3. Accessibility: Gunakan semantic HTML dan sertakan ARIA label yang sesuai untuk screen reader.

  4. Kompatibilitas Tema: Selalu gunakan CSS variables untuk warna untuk memastikan widget bekerja di tema light dan dark.

Use Case Umum

1. Widget Visualisasi Data

  • Chart dan graph (line, bar, pie)
  • Heatmap dan distribution plot
  • Visualisasi timeline
  • Tabel perbandingan

2. Widget Display Dokumen

  • Card preview dokumen
  • Tabel field-value
  • Indicator status dengan metadata
  • Text terformat dengan styling

3. Widget Interaktif

  • Form yang embedded di chat
  • Button group untuk quick action
  • Selection control
  • Filter interaktif

4. Information Card

  • Profil pengguna
  • Card produk
  • Display notifikasi
  • Summary box

Troubleshooting

Widget Tidak Di-render

Gejala: Widget muncul sebagai error message atau tidak di-render sama sekali

Kemungkinan Penyebab & Solusi: - Syntax Template Invalid: Periksa HTML untuk error syntax Jinja2. Masalah umum termasuk tag yang tidak ditutup, quote yang tidak cocok, atau nama variable yang salah. - JSON Schema Invalid: Validasi Input Schema Anda menggunakan JSON Schema validator. - Data Tidak Cocok: Pastikan AI agent menyediakan data yang sesuai dengan struktur schema. - Masalah Permission: Verifikasi bahwa pengguna memiliki read permission pada widget.

Masalah Styling

Gejala: Widget muncul tanpa style atau style bertentangan dengan page

Solusi: - Periksa syntax CSS untuk error - Pastikan Anda menggunakan CSS variables untuk theme-aware styling - Ingat bahwa Shadow DOM mengisolasi style - external style tidak akan mempengaruhi widget Anda - Test di tema light dan dark

Chart Tidak Terinisialisasi

Gejala: Widget chart di-render tapi chart tidak muncul

Solusi: - Verifikasi isChart: true di-set di object data - Periksa bahwa attribute data-chart-type ada di container chart - Pastikan struktur data chart sesuai dengan requirement Frappe Charts - Periksa browser console untuk JavaScript error

Perbedaan Preview vs. Live Rendering

Gejala: Widget terlihat berbeda di preview dibanding di chat aktual

Solusi: - Pastikan Preview Sample Data persis sesuai struktur schema - Periksa dependensi pada real-time data yang tidak ada di sample - Verifikasi widget tidak bergantung pada external context yang tidak tersedia di preview

AI Agent Tidak Menggunakan Widget

Gejala: Widget terhubung ke agent tapi tidak pernah dipanggil

Solusi: - Perbaiki deskripsi widget agar tujuannya lebih jelas - Gunakan keyword yang lebih spesifik di deskripsi - Pastikan widget benar-benar terhubung di child table Widgets agent - Periksa bahwa agent memiliki instruksi yang sesuai untuk menggunakan output visual saat relevan - Test dengan request eksplisit (misalnya, "tunjukkan chart...")

Fitur Terkait

  • TM AI Chat Agent: Agent yang dapat memanggil widget selama percakapan
  • TM AI Context: Menyediakan background data yang dapat digunakan dalam rendering widget
  • Frappe Charts: Library chart yang terintegrasi untuk widget visualisasi data
  • Shadow DOM: Teknologi web yang digunakan untuk mengisolasi style dan script widget

Catatan Teknis

Pipeline Rendering

  1. AI agent memanggil widget sebagai function/tool dengan payload data
  2. Server menerima invokasi widget dengan data
  3. Server memvalidasi data terhadap Input Schema
  4. Server me-render Template HTML dengan data menggunakan Jinja2
  5. HTML + CSS yang di-render dikembalikan ke client
  6. Client membuat container Shadow DOM
  7. HTML dan CSS diinjeksi ke Shadow DOM
  8. Jika chart widget, Frappe Charts diinisialisasi
  9. Widget ditampilkan di interface chat

Isolasi Shadow DOM

Widget menggunakan Shadow DOM (standar Web Components) untuk: - Mencegah konflik CSS antara widget dan page - Mengisolasi eksekusi JavaScript - Memungkinkan reusability komponen - Mendukung fitur advanced seperti chart tanpa dependensi global

Dukungan Jinja2

Template engine Jinja2 penuh tersedia termasuk: - Variables: {{ variable }} - Conditional: {% if condition %} ... {% endif %} - Loop: {% for item in items %} ... {% endfor %} - Filter: {{ value | filter }} - Macro dan import (untuk widget kompleks)

CSS Variables yang Tersedia

Variable tema umum yang tersedia di widget: - --card-bg: Warna background card - --border-color: Warna border - --text-color: Warna text utama - --text-muted: Warna text muted/sekunder - --primary-color: Warna primary brand - --bg-color: Warna background page - --shadow-sm, --shadow-md: Nilai shadow - --border-radius: Border radius standar

Terakhir Diperbarui: Januari 2026
Versi: 1.0
Modul: TechMaju AI

Discard
Save
Draft

Previous Page

Left

Next Page

Right

On this page

Review Changes ← Back to Content
Message Status Space Raised By Last update on