Membuat ekstensi tile

Mulai Looker 24.0, ekstensi dapat dikembangkan untuk dijalankan di kartu dalam dasbor. Ekstensi yang mendukung dijalankan sebagai kartu atau visualisasi dapat ditambahkan saat dasbor dalam mode edit atau disimpan ke dasbor sebagai visualisasi dari Jelajah. Ekstensi juga dapat dikonfigurasi sebagai kartu di dasbor LookML.

Contoh ekstensi yang dapat digunakan sebagai kartu dasbor tersedia:

Menggunakan Looker Extension SDK dengan ekstensi kartu

Ekstensi kartu memerlukan parameter mount_points untuk ditentukan dalam file manifes project LookML agar ekstensi dimuat sebagai kartu ke dalam dasbor. Ada dua jenis mount_points yang terkait dengan ekstensi kartu:

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }
  • dashboard_vis — Jika diaktifkan, ekstensi akan muncul di opsi visualisasi Eksplorasi, tempat ekstensi dapat dipilih sebagai visualisasi dan disimpan sebagai kartu dasbor. Saat dasbor dijalankan, dasbor akan menjalankan kueri yang terkait dengan kartu dan membuat data tersedia untuk ekstensi. Hal ini mirip dengan cara kerja visualisasi kustom. Perbedaan utama antara visualisasi kustom dan ekstensi yang berjalan di kartu dasbor yang mengaktifkan dashboard_vis adalah bahwa ekstensi dapat melakukan panggilan Looker API.
  • dashboard_tile — Jika diaktifkan, ekstensi akan muncul di panel Ekstensi yang ditampilkan saat pengguna mengedit dasbor dan memilih opsi Ekstensi setelah mengklik tombol Tambahkan. Jenis ekstensi ini bertanggung jawab untuk mengambil datanya sendiri, bukan membuat kueri kartu secara otomatis menyediakan data untuk ekstensi.

Titik pemasangan tambahan, standalone, menyebabkan ekstensi muncul di bagian Aplikasi pada menu utama Looker. Ekstensi dapat memiliki beberapa titik pemasangan yang ditentukan. Saat runtime, ekstensi diberi tahu cara pemasangannya dan dapat menyesuaikan perilakunya. Misalnya, ekstensi standalone mungkin perlu menyetel tingginya sendiri, sedangkan ekstensi kartu tidak perlu.

API tambahan ekstensi kartu

Ekstensi kartu disediakan dengan API dan data tambahan saat runtime. Objek ini diperoleh dari konteks ekstensi:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)
  • tileSDK — Menyediakan fungsi khusus kartu untuk memungkinkan ekstensi berinteraksi dengan host dasbor Looker. Misalnya, untuk mengizinkan ekstensi menampilkan dan menghapus pesan error.
  • tileHostData — Menyediakan data kartu ke ekstensi. Data diperbarui secara otomatis berdasarkan interaksi dengan dasbor hosting. Contohnya adalah indikator isDashboardEditing.
  • visualizationSDK — Menyediakan fungsi khusus visualisasi agar ekstensi dapat berinteraksi dengan host dasbor Looker. Contohnya adalah fungsi updateRowLimit.
  • visualizationData — Menyediakan data visualisasi ke ekstensi. Data diperbarui secara otomatis berdasarkan interaksi dengan dasbor hosting. Data ini mirip dengan data yang diberikan ke visualisasi kustom.

Membangun ekstensi reaktif

Iframe tempat ekstensi berjalan akan otomatis diubah ukurannya saat jendela host Looker induk diubah ukurannya. Hal ini otomatis tercermin di jendela konten iframe. Komponen iframe tidak memiliki padding atau margin, sehingga ekstensi harus menyediakan padding dan marginnya sendiri agar terlihat konsisten dengan aplikasi Looker. Untuk ekstensi mandiri, ekstensi yang mengontrol tinggi ekstensi. Untuk ekstensi yang berjalan di kartu dasbor atau visualisasi Jelajahi, jendela konten iframe akan otomatis disetel ke tinggi yang disediakan oleh iframe.

Pertimbangan rendering

Penting untuk diperhatikan bahwa ekstensi kartu akan dirender saat dasbor didownload sebagai PDF atau gambar. Renderer mengharapkan agar petak memberi tahu saat rendering selesai. Jika hal ini tidak dilakukan, perender akan berhenti merespons. Berikut adalah contoh cara memberi tahu perender bahwa petak telah dirender.

  const { extensionSDK } = useContext(ExtensionContext40)

  useEffect(() => {
    extensionSDK.rendered()
  }, [])

Animasi juga harus dinonaktifkan saat merender. Berikut adalah contoh konfigurasi animasi yang dinonaktifkan saat merender:

  const { lookerHostData} = useContext(ExtensionContext40)
  const isRendering = lookerHostData?.isRendering

  const config = isRendering
    ? {
        ...visConfig,
        valueCountUp: false,
        waveAnimateTime: 0,
        waveRiseTime: 0,
        waveAnimate: false,
        waveRise: false,
      }
    : visConfig

  if (mountPoint === MountPoint.dashboardVisualization) {
    return <VisualizationTile config={config} />
  }

Fungsi dan properti Tile SDK

Tile SDK menyediakan fungsi yang memungkinkan ekstensi kartu berinteraksi dengan dasbor hostingnya.

Fungsi dan properti yang tersedia ditampilkan dalam tabel berikut:

Fungsi atau properti Deskripsi
tileHostData (properti) Menampung data khusus untuk ekstensi petak. Lihat bagian Data Tile SDK untuk mengetahui detailnya.
addError Saat dipanggil, dasbor atau Jelajah akan menampilkan pesan error di bawah visualisasi.
clearError Saat dipanggil, dasbor atau Eksplorasi akan menyembunyikan pesan error yang ditampilkan di bawah visualisasi.
openDrillMenu Untuk ekstensi visualisasi, panggilan ini membuka menu penelusuran. Panggilan ini diabaikan jika ekstensi bukan visualisasi ekstensi kartu.
runDashboard Menjalankan dasbor saat ini. Panggilan ini diabaikan oleh ekstensi visualisasi kartu yang berjalan di Eksplorasi.
stopDashboard Menghentikan dasbor yang sedang berjalan. Panggilan ini diabaikan oleh ekstensi visualisasi kartu yang berjalan di Eksplorasi.
updateFilters Memperbarui filter di dasbor atau Eksplorasi saat ini.
openScheduleDialog Membuka dialog jadwal. Panggilan ini diabaikan saat berjalan di Eksplorasi.
toggleCrossFilter Mengaktifkan/menonaktifkan filter silang. Panggilan ini diabaikan saat berjalan di Eksplorasi.

Data Tile SDK

Properti data SDK kartu yang tersedia ditampilkan dalam tabel berikut:

Properti Deskripsi
isExploring Jika benar (true), menunjukkan bahwa kartu sedang dikonfigurasi sebagai visualisasi di dalam Eksplorasi.
dashboardId ID dasbor kartu yang sedang dirender. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.
elementId ID elemen kartu yang sedang dirender. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.
queryId ID kueri kartu yang dirender jika dikaitkan dengan visualisasi. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.

queryId adalah ID kueri yang dibuat saat visualisasi bawaan dibuat di Eksplorasi Looker. Tidak berisi filter atau pemfilteran silang yang akan diterapkan ke dasbor. Untuk mencerminkan data yang ditampilkan di QueryResponse, filter dan filter silang harus diterapkan dan kueri baru dibuat. Akibatnya, mungkin ada properti yang lebih berguna daripada queryId. Lihat filteredQuery untuk objek kueri dengan filter yang diterapkan.
querySlug Slug kueri kartu yang dirender jika dikaitkan dengan visualisasi. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.

querySlug adalah slug kueri yang dibuat saat visualisasi dibuat di Eksplorasi Looker. Tidak berisi filter atau pemfilteran silang yang diterapkan ke dasbor. Untuk mencerminkan data yang ditampilkan di QueryResponse, filter dan filter silang harus diterapkan dan kueri baru dibuat. Akibatnya, mungkin ada properti yang lebih berguna daripada querySlug. Lihat filteredQuery untuk objek kueri dengan filter yang diterapkan.
dashboardFilters Filter yang diterapkan ke dasbor. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.
dashboardRunState Menunjukkan apakah dasbor sedang berjalan. Jika kartu dikonfigurasi sebagai Jelajahi, statusnya adalah UNKNOWN.

Karena alasan performa dasbor, status proses mungkin tidak pernah ditampilkan sebagai berjalan. Hal ini umumnya terjadi jika tidak ada kartu lain yang terkait dengan kueri, termasuk kartu yang terkait dengan ekstensi. Jika ekstensi perlu mengetahui dengan pasti bahwa dasbor telah dijalankan, mendeteksi perbedaan dalam lastRunStartTime adalah cara yang andal.
isDashboardEditing Jika benar (true), dasbor sedang diedit. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.
isDashboardCrossFilteringEnabled Jika benar (true), filter silang diaktifkan di dasbor. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.
filteredQuery Objek kueri yang cocok dengan ID kueri yang terkait dengan elemen dasbor pokok yang menerapkan filter dasbor dan perubahan zona waktu yang dilakukan di tingkat dasbor.
lastRunSourceElementId ID elemen ekstensi kartu yang memicu eksekusi dasbor terakhir. ID akan tidak ditentukan jika eksekusi dasbor dipicu oleh tombol Jalankan dasbor atau muat ulang otomatis, atau jika eksekusi dipicu menggunakan SDK sematan. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.

Perhatikan bahwa lastRunSourceElementId dapat sama dengan ID elemen instance ekstensi saat ini. Misalnya, jika ekstensi memicu eksekusi dasbor, ekstensi akan diberi tahu saat eksekusi dasbor dimulai dan selesai.
lastRunStartTime Menunjukkan waktu mulai eksekusi dasbor terakhir. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.

Perhatikan bahwa waktu mulai dan berakhir yang dilaporkan tidak boleh digunakan untuk merekam metrik performa.
lastRunEndTime Menunjukkan waktu berakhir operasi dasbor terakhir. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi. Jika kartu sedang berjalan, properti ini tidak akan diisi.

Perhatikan bahwa waktu mulai dan berakhir yang dilaporkan tidak boleh digunakan untuk merekam metrik performa.
lastRunSuccess Menunjukkan apakah dasbor terakhir berhasil dijalankan atau tidak. Jika kartu dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi. Jika kartu sedang berjalan, properti ini tidak akan diisi.

Fungsi dan properti Visualization SDK

Fungsi dan properti SDK visualisasi yang tersedia ditampilkan dalam tabel berikut:

Fungsi atau properti Deskripsi
visualizationData (properti) Visualisasi (kombinasi data visConfig dan queryResponse).
visConfig (properti) Data konfigurasi visualisasi:

  • Konfigurasi pengukuran
  • Konfigurasi dimensi
  • Kalkulasi tabel
  • Konfigurasi pivot
  • Konfigurasi visualisasi

Setelan ini digunakan untuk menyesuaikan tampilan dan nuansa visualisasi di Eksplorasi.
queryResponse (properti) Data respons dari kueri
configureVisualization Menetapkan konfigurasi default untuk visualisasi ekstensi. Konfigurasi akan dirender di dalam editor visualisasi Jelajahi. Metode ini hanya boleh dipanggil satu kali.
setVisConfig Memperbarui konfigurasi visualisasi.
updateRowLimit Memperbarui batas baris kueri.

Data SDK Visualisasi

SDK visualisasi terdiri dari hal-hal berikut:

  • Data konfigurasi visualisasi
  • Data respons kueri

Data konfigurasi visualisasi

Properti Deskripsi
queryFieldMeasures Informasi pengukuran
queryFieldDimensions Informasi dimensi
queryFieldTableCalculations Informasi kalkulasi tabel
queryFieldPivots Informasi pivot
visConfig Data konfigurasi visual. Konfigurasi ini harus digabungkan dengan konfigurasi default dan diterapkan ke visualisasi yang dirender oleh ekstensi. 
export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Data respons kueri

Properti Deskripsi
data Array data baris
fieldMeasures Informasi pengukuran kolom.
fieldDimensions Informasi dimensi kolom.
fieldTableCalculations Informasi kalkulasi tabel kolom.
fieldPivots Informasi pivot kolom.
fieldMeasureLike Array gabungan informasi ukuran kolom dan kalkulasi tabel yang berperilaku seperti ukuran.
fieldDimensionLike Array gabungan informasi dimensi kolom dan kalkulasi tabel yang berperilaku seperti dimensi.

Menggunakan Embed SDK

Penggunaan Embed SDK dalam ekstensi kartu tidak direkomendasikan karena alasan berikut:

  • Ada kemungkinan ekstensi akan merender dasbor yang berisi petak ekstensi. Framework ekstensi tidak dapat mendeteksi hal ini, dan akibatnya, browser dapat mengalami error.
  • Rendering PDF konten sematan di dalam ekstensi kartu tidak berfungsi.