Membuat ekstensi kartu

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

Tersedia contoh ekstensi yang dapat digunakan sebagai kartu dasbor:

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 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 dalam opsi visualisasi Jelajah, tempat ekstensi dapat dipilih sebagai visualisasi dan disimpan sebagai kartu dasbor. Saat dasbor dijalankan, dasbor akan mengeksekusi kueri yang terkait dengan kartu dan membuat data tersedia untuk ekstensi. 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 tersebut 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 ke ekstensi.

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

API tambahan ekstensi kartu

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

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

Mem-build ekstensi reaktif

iframe tempat ekstensi dijalankan akan otomatis diubah ukurannya saat jendela host Looker induk berubah ukuran. Hal ini secara otomatis akan tercermin di jendela konten iframe. Komponen iframe tidak memiliki padding atau margin sehingga ekstensi dapat menyediakan padding dan marginnya sendiri sehingga terlihat konsisten dengan aplikasi Looker. Untuk ekstensi mandiri, tinggi ekstensi dapat dikontrol oleh ekstensi. Untuk ekstensi yang berjalan di ubin 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. Perender mengharapkan bahwa kartu akan memberi tahu saat rendering selesai. Jika tindakan ini tidak dilakukan, perender akan berhenti merespons. Berikut adalah contoh cara memberi tahu perender bahwa kartu telah dirender.

  const { extensionSDK } = useContext(ExtensionContext40)

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

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

  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 SDK Kartu

SDK kartu 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) Menghosting data khusus untuk ekstensi kartu. Lihat bagian data SDK Kartu untuk mengetahui detailnya.
addError Ketika dipanggil, dasbor atau {i>Explore<i} akan menampilkan pesan {i>error<i} di bawah visualisasi.
clearError Saat dipanggil, dasbor atau Explore akan menyembunyikan pesan error yang ditampilkan di bawah visualisasi.
openDrillMenu Untuk ekstensi visualisasi, panggilan ini membuka menu penelusuran. Panggilan ini akan diabaikan jika ekstensi bukan visualisasi ekstensi kartu.
runDashboard Menjalankan dasbor saat ini. Panggilan ini diabaikan oleh ekstensi visualisasi kartu yang berjalan di Explore.
stopDashboard Menghentikan dasbor yang berjalan. Panggilan ini diabaikan oleh ekstensi visualisasi kartu yang berjalan di Explore.
updateFilters Filter update di dasbor saat ini atau Explore.
openScheduleDialog Membuka dialog jadwal. Panggilan ini akan diabaikan saat dijalankan di Explore.
toggleCrossFilter Mengaktifkan/menonaktifkan filter silang. Panggilan ini akan diabaikan saat dijalankan di Explore.

Data SDK Kartu

Properti data SDK kartu yang tersedia ditampilkan dalam tabel berikut:

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

queryId adalah ID kueri yang dibuat saat visualisasi menjadi bawaan di Jelajah Looker. Dasbor ini tidak berisi filter atau filter silang apa pun untuk diterapkan ke dasbor. Untuk mencerminkan data yang ditampilkan di QueryResponse, filter dan filter silang harus diterapkan serta kueri baru dibuat. Akibatnya, mungkin ada properti yang lebih berguna daripada queryId. Lihat filteredQuery untuk melihat objek kueri dengan filter yang diterapkan.
querySlug Kueri slug kartu yang dirender jika terkait dengan visualisasi. Jika ubin dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.

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

Untuk alasan performa dasbor, runstate mungkin tidak pernah ditampilkan sebagai running. Hal ini umumnya terjadi jika tidak ada ubin lain yang terkait dengan kueri, termasuk ubin yang dikaitkan dengan ekstensi. Jika ekstensi perlu mengetahui secara pasti bahwa dasbor telah dijalankan, mendeteksi perbedaan dalam lastRunStartTime adalah cara yang dapat diandalkan.
isDashboardEditing Jika true (benar), dasbor sedang diedit. Jika ubin dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.
isDashboardCrossFilteringEnabled Jika true (benar), filter silang akan diaktifkan di dasbor. Jika ubin dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.
filteredQuery Objek kueri yang cocok dengan ID kueri yang dikaitkan dengan elemen dasbor pokok, yang menerapkan filter dasbor dan perubahan zona waktu apa pun yang dibuat di tingkat dasbor.
lastRunSourceElementId ID elemen ekstensi kartu yang memicu berjalannya dasbor terakhir. ID tidak akan ditentukan jika pengoperasian dasbor dipicu oleh tombol Run atau autorefresh di dasbor, atau jika pengoperasian dipicu menggunakan SDK sematan. Jika ubin dikonfigurasi sebagai Jelajah, properti ini tidak akan diisi.

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

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

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

Fungsi dan properti SDK Visualisasi

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:

  • Mengukur konfigurasi
  • Konfigurasi dimensi
  • Penghitungan tabel
  • Konfigurasi pivot
  • Konfigurasi visualisasi

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

Data SDK visualisasi

SDK visualisasi terdiri dari hal berikut:

  • Data konfigurasi visualisasi
  • Data respons kueri

Data konfigurasi visualisasi

Properti Deskripsi
queryFieldMeasures Informasi pengukuran
queryFieldDimensions Informasi dimensi
queryFieldTableCalculations Informasi penghitungan tabel
queryFieldPivots Informasi pivot
visConfig Data konfigurasi visual. Fungsi 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 ukuran kolom.
fieldDimensions Informasi dimensi kolom.
fieldTableCalculations Informasi penghitungan tabel kolom.
fieldPivots Informasi pivot kolom.
fieldMeasureLike Array gabungan dari informasi ukuran lapangan dan perhitungan tabel yang berperilaku seperti ukuran.
fieldDimensionLike Array gabungan dari informasi dimensi kolom dan penghitungan tabel yang berperilaku seperti dimensi.