Referensi API visualisasi kustom 2.0

Panggilan ke fungsi looker.plugins.visualizations.add adalah titik entri ke Visualization API. Fungsi ini menerima objek visualisasi yang sepenuhnya menentukan visualisasi kustom Anda.

Berikut contoh visualisasi:

looker.plugins.visualizations.add({
    create: function(element, config){
        element.innerHTML = "<h1>Ready to render!</h1>";
    },
    updateAsync: function(data, element, config, queryResponse, details, doneRendering){
        var html = "";
        for(var row of data) {
            var cell = row[queryResponse.fields.dimensions[0].name];
            html += LookerCharts.Utils.htmlForCell(cell);
        }
        element.innerHTML = html;
        doneRendering()
    }
});

Lingkungan

Karena Visualization API adalah JavaScript biasa, Anda dapat menggunakan library JavaScript apa pun untuk memvisualisasikan data.

Kode JavaScript Anda akan berjalan di iframe dengan sandbox, terpisah dari instance Looker Anda. Namun, penulis visualisasi kustom bertanggung jawab untuk memastikan bahwa kode yang mereka tulis aman.

Seperti semua pengembangan web, mendukung berbagai browser web (Chrome, Edge, Firefox) terkadang dapat menjadi masalah. Visualization API berfungsi di semua browser yang didukung Looker, tetapi Anda harus memastikan dukungan browser untuk kode kustom Anda. Misalnya, penggunaan ES6 seperti let atau ()=> akan berfungsi di sebagian besar browser, tetapi dapat menyebabkan kegagalan di IE11 atau saat merender PDF menggunakan PhantomJS.

Penginstalan

Anda menginstal visualisasi kustom dengan menentukan manifes menggunakan formulir Admin > Platform > Visualizations. Manifes terdiri dari ID string unik, label yang dapat dibaca manusia, URI visualisasi Anda, dan link ke dependensi yang Anda perlukan (misalnya: d3, jQuery, underscore).

Visualisasi kustom harus disajikan sebagai konten HTTPS secara eksternal ke Looker. Jika Anda bermigrasi dari versi pertama API visualisasi kustom, Anda mungkin memiliki file di direktori looker/plugins/visualizations. Lokasi ini masih dapat diakses, dan jalur relatif ke visualisasi Anda dapat diberikan, tetapi sebaiknya migrasikan konten Anda ke lokasi lain. Karena direktori /plugins tidak ada di Sistem File Bersama, lingkungan bercluster tidak akan memiliki akses ke file visualisasi Anda di semua node.

Objek visualisasi

Objek visualisasi menggunakan properti wajib, opsional, dan tambahan berikut.

Properti wajib

• Fungsi create

  Fungsi ini dipanggil satu kali, saat visualisasi Anda pertama kali digambar di halaman. Anda diharapkan menyiapkan apa pun yang Anda inginkan agar visualisasi selalu tersedia. Anda dapat memuat library atau membuat kumpulan elemen dan kontrol yang akan Anda gunakan nanti.

  Lihat detail tentang fungsi create →

• updateAsync / update fungsi

  Fungsi ini dipanggil setiap kali status visualisasi Anda mungkin perlu diubah. Metode ini akan selalu dipanggil setelah create, dan dapat dipanggil berkali-kali, sehingga harus secepat mungkin.

  Fungsi ini dapat dipanggil karena berbagai alasan, tetapi biasanya saat kueri yang akan divisualisasikan diubah, opsi konfigurasi diubah, atau visualisasi diubah ukurannya.

  Fungsi ini memiliki versi sinkron dan asinkron :emdash; Anda hanya perlu menentukan salah satunya. (Error terjadi jika Anda menentukan keduanya.) Metode asinkron lebih andal untuk rendering PDF karena sifat iframe.

  Lihat detail tentang fungsi update ini →

Properti opsional

• options objek

  Objek yang menjelaskan opsi yang dapat ditetapkan pengguna pada visualisasi Anda.

  Lihat detail tentang mengekspos UI konfigurasi →

• destroy fungsi Belum diimplementasikan di API V2

  Fungsi yang dipanggil tepat sebelum visualisasi dihapus dari halaman. Gunakan fungsi ini untuk membersihkan pemroses peristiwa atau status lainnya. Metode ini mungkin tidak pernah dipanggil jika, misalnya, pengguna menutup jendela.

Properti yang ditambahkan

Looker menambahkan properti berikut ke objek Anda secara otomatis setelah visualisasi diteruskan ke looker.plugins.visualizations.add. Anda dapat mereferensikannya menggunakan this dalam konteks fungsi create, update, updateAsync, dan destroy.

• addError function

  Fungsi yang dapat dipanggil oleh kode visualisasi Anda untuk memberi tahu UI agar menampilkan pesan error, bukan visualisasi. Metode ini mengambil objek error.

  Setelah ditambahkan, error akan tetap terlihat hingga clearErrors dipanggil.

  Contoh:

  this.addError({
      title: "Two Dimensions Required",
      message: "This really great visualization requires two dimensions."
  });
  

• Fungsi clearErrors

  Fungsi yang dapat dipanggil oleh kode visualisasi Anda untuk menghapus error yang ditambahkan menggunakan addError.

  Contoh:

  this.clearErrors();
  

• trigger function

  Fungsi yang dapat dipanggil untuk memicu peristiwa di luar visualisasi.

  Lihat detail tentang acara →

  Contoh:

  this.trigger("limit", [20]);
  

Fungsi create

Fungsi create akan meneruskan dua parameter, element dan config.

create: function(element, config){
  // Your update code here.
},

Parameter

• element DOMElement

  Elemen DOM yang mewakili penampung untuk merender visualisasi Anda.

• config objek

  Objek yang mewakili nilai opsi konfigurasi apa pun yang telah ditetapkan pengguna untuk diagram ini.

  Contoh: {my_configuration_option: "User Value"}

Fungsi updateAsync dan update

Metode yang direkomendasikan untuk memperbarui visualisasi Anda adalah metode updateAsync. Metode ini memungkinkan visualisasi Anda melakukan tindakan asinkron, seperti memuat file atau mengirim permintaan web.

Versi fungsi ini memiliki parameter tambahan, yaitu callback yang akan dipanggil saat rendering selesai:

updateAsync: function(data, element, config, queryResponse, details, done){
    // An example of an asynchronous update, fetching a file.
    d3.request("https://example.com/fun-file.docx").response(function(xhr) {
        // Your update code here that uses this file.
        done();
    });
}

Memberi tahu Looker saat visualisasi selesai dirender memungkinkan Looker mengoptimalkan rendering PDF dan memastikan bahwa gambar visualisasi diambil dengan benar.

Beberapa visualisasi lama menggunakan fungsi update. Fungsi ini masih berfungsi, tetapi bukan metode yang direkomendasikan, karena penggunaannya berarti Looker tidak akan diberi tahu saat visualisasi dirender sepenuhnya. Fungsi update akan meneruskan lima parameter:

update: function(data, element, config, queryResponse, details){
  // Your update code here.
}

Parameter

• data array

  Array baris yang mewakili data saat ini dalam kueri. Mungkin null.

  Setiap baris adalah objek dengan kunci yang mewakili nama kolom, dan nilai yang mewakili objek "sel". Berikut detail tentang cara menangani objek sel.

• element DOMElement

  Elemen DOM yang mewakili penampung untuk merender visualisasi Anda.

• Objek config

  Objek yang merepresentasikan nilai opsi konfigurasi yang telah ditetapkan pengguna untuk diagram ini.

  Contoh: {my_configuration_option: "User Value"}

• queryResponse objek

  Objek yang merepresentasikan metadata tentang kueri saat ini, seperti metadata tentang kolom. Mungkin null.

• details objek

  Detail tentang konteks rendering saat ini. Berisi informasi tentang alasan diagram dirender dan hal yang telah berubah. Biasanya, informasi ini hanya digunakan dalam kasus lanjutan.

  Terkait dengan filter silang di dasbor Looker yang menggunakan pengalaman dasbor baru, atribut yang diizinkan mencakup crossfilterEnabled dan crossfilters.

  Atribut print dapat digunakan bersama dengan fungsi done untuk meningkatkan rendering PDF untuk visualisasi kustom, terutama yang menyertakan animasi. Contoh:

  if (details.print) {
          done();
  }
  

• done function

  Callback untuk menunjukkan bahwa visualisasi telah dirender sepenuhnya. Fungsi ini sangat penting untuk dipanggil jika visualisasi Anda perlu melakukan panggilan asinkron atau perlu dirender sebagai PDF.

Merender Data

Looker memiliki serangkaian alat pemformatan data yang lengkap di LookML yang dapat digunakan untuk menyesuaikan tampilan dan perilaku titik data. Alat ini mencakup setelan LookML tingkat kolom seperti format nilai kustom, HTML, link perincian, dan tindakan data.

Sel memiliki properti value, yang merupakan satu-satunya properti yang ada dalam semua kasus. Properti ini adalah jenis JavaScript yang cocok dengan jenis kolom tempat sel berada. Namun, menyisipkan properti value langsung ke HTML atau SVG tidak aman, karena tidak ada pelepasan HTML yang dilakukan, dan beberapa nilai kolom adalah objek atau array JavaScript kompleks yang akan dirender dengan cara yang tidak diinginkan atau membingungkan.

Untuk memastikan semua visualisasi merender item ini secara konsisten dan aman, ada sejumlah fungsi utilitas untuk mengubah metadata sel yang diteruskan ke diagram Anda dalam data menjadi representasi yang berbeda untuk tujuan yang berbeda. Metadata sel dapat mengompresi atau menghilangkan kolom tertentu dalam beberapa kasus, dan fungsi bantuan ini akan memungkinkan Anda memberikan pengalaman yang konsisten.

Semua fungsi bantuan ini tersedia di objek LookerCharts.Utils global.

• LookerCharts.Utils.textForCell(cell)

  Fungsi ini menerima sel dan menampilkan representasi stringnya yang sesuai untuk ditampilkan. Nilai ini akan selalu berupa string – fungsi ini tidak pernah menampilkan null atau jenis lainnya.

• LookerCharts.Utils.htmlForCell(cell)

  Fungsi ini menerima sel dan menampilkan string yang berisi HTML. Nilainya akan selalu berupa string – fungsi ini tidak pernah menampilkan null atau jenis lainnya.

  Output fungsi ini di-escape dengan benar dan cocok untuk langsung disisipkan ke dalam HTML elemen Anda. HTML output juga akan menampilkan menu perincian dengan benar saat diklik jika sesuai untuk data.

• LookerCharts.Utils.filterableValueForCell(cell)

  Fungsi ini menerima sel dan menampilkan string sintaksis filter lanjutan Looker yang akan cocok dengan nilai sel ini.

• LookerCharts.Utils.toggleCrossfilter({row, pivot, event})

  Fungsi ini menerima baris, pivot, atau peristiwa dan digunakan untuk memeriksa apakah pemfilteran silang diaktifkan untuk visualisasi. Contoh berikut menunjukkan cara menambahkan pemroses peristiwa ke elemen yang memeriksa apakah pemfilteran silang diaktifkan saat peristiwa terjadi:

  d3.select("#myElement")
  .on("click", function (d) {
      if (details.crossfilterEnabled) {
              LookerCharts.Utils.toggleCrossfilter({
                  row: d.row,
                  event: d3.event,
              });
      } else {
        // ... handle click when cross-filtering is not enabled
      }
  });
  

• LookerCharts.Utils.getCrossfilterSelection(row, pivot?)

  Fungsi ini menerima baris atau pivot dan digunakan untuk memeriksa apakah baris atau pivot tersebut dipilih dalam visualisasi kustom. Fungsi ini menampilkan enum untuk CrossfilterSelection {NONE, SELECTED, UNSELECTED} 0 jika NONE, 1 jika SELECTED, dan 2 jika UNSELECTED.

  Contoh berikut menerapkan warna pengisi secara bersyarat ke baris jika baris tersebut difilter silang dan menerapkan warna default jika pemfilteran silang tidak diaktifkan untuk baris tersebut:

  d3.select("#myElement")
  .attr("fill", function (d) {
      const crossfilter = LookerCharts.Utils.getCrossfilterSelection(d.row)
      if (details.crossfilterEnabled && crossfilter === 1) {
              return d.color
      } else {
              return "#DEE1E5" //Hex used for unselected elements in native visualizations
  ...
  

• LookerCharts.Utils.openDrillMenu(options)

  Output htmlForCell akan otomatis menampilkan menu perincian jika diperlukan, tetapi hal ini mungkin tidak sesuai untuk jenis rendering tertentu. (Misalnya, SVG tidak dapat merender HTML, tetapi Anda mungkin ingin menangkap peristiwa klik untuk memulai perincian.)

  Objek options memiliki parameter berikut:

  • links Wajib array

    Array objek yang ditampilkan dari properti links sel. Jika Anda ingin menampilkan link untuk beberapa sel sekaligus, Anda dapat menggabungkan array ini terlebih dahulu. Untuk link kustom, berikan array objek dengan bentuk berikut:

    { label: string, type: 'drill', type_label: string, url: url }

  • event Peristiwa DOM HTML

    Peristiwa klik (atau lainnya) yang menyebabkan peristiwa lihat perincian. Looker akan menggunakannya untuk menentukan tempat menempatkan menu lihat perincian. Jika Anda tidak memilikinya, coba teruskan objek dengan koordinat pageX dan pageY.

  Contoh:

  for (var row of data) {
      var cell = row[queryResponse.fields.dimensions[0].name];
      var cellElement = myBuildElementFunction(cell);
      cellElement.onclick = function(event) {
          LookerCharts.Utils.openDrillMenu({
              links: cell.links,
              event: event
          });
      };
      // ... more visualization stuff...
  }
  

Menampilkan UI konfigurasi

Parameter options adalah objek yang kuncinya adalah ID arbitrer untuk nama opsi, dan nilainya adalah objek yang menjelaskan informasi tentang opsi tersebut.

Berikut contohnya:

options: {
    color_range: {
      type: "array",
      label: "Color Range",
      display: "colors"
    },
   top_label: {
      type: "string",
      label: "Label (for top)",
      placeholder: "My Great Chart"
    },
    transport_mode: {
      type: "string",
      label: "Mode of Transport",
      display: "select",
      values: [
         {"Airplane": "airplane"},
         {"Car": "car"},
         {"Unicycle": "unicycle"}
      ],
      default: "unicycle"
    }
}

Parameter Objek Opsi

Objek option memiliki parameter dasar, properti khusus tampilan, dan opsi pengorganisasian berikut.

Parameter dasar

• type string

  Jenis data opsi.

  Nilai yang Diizinkan: string (default), number, boolean, array

• label string

  Label opsi yang dapat dibaca manusia yang akan ditampilkan kepada pengguna.

• default

  Nilai default opsi. Jika tidak ditentukan, nilai opsi adalah null. Nilai ini harus memiliki jenis yang sama dengan type.

• display string

  Nilai type tertentu dapat ditampilkan di UI dengan berbagai cara.

  • jika type adalah string:

    Nilai yang Diizinkan: text (default), select, radio

  • jika type adalah number:

    Nilai yang Diizinkan: number (default), range

  • jika type adalah array:

    Nilai yang Diizinkan: text (default), color, colors

• placeholder string

  Untuk nilai display yang mendukungnya, contoh nilai atau penjelasan untuk memberi pengguna petunjuk tentang apa yang harus diketik.

Properti khusus tampilan

• values array objek

  Jika display adalah radio atau select, array yang berisi label dan nilai yang akan dicantumkan di antarmuka.

  Setiap item dalam array harus berupa objek dengan satu pasangan nilai kunci, yang mewakili label dan nilai opsi. Label hanya akan ditampilkan di UI; pada waktu render, Anda hanya akan menerima nilainya.

  Contoh:

  values: [
      {"Center": "c"},
      {"Left": "l"},
      {"Right": "r"}
  ]
  

  Jika display adalah radio, setiap opsi juga dapat diberi description:

  values: [
      {"Cool": "c"},
      {"Uncool": {
              value: "unc",
              description: "Only choose this if the data is very uncool."
          }
      }
  ]
  

• max number

  Jika display adalah range, jumlah maksimum yang diizinkan untuk dipilih oleh penggeser rentang.

• min number

  Jika display adalah range, jumlah minimum yang diizinkan untuk dipilih oleh penggeser rentang.

• step number

  Jika display adalah range, jumlah yang diwakili oleh setiap tanda pada penggeser rentang.

Opsi pengorganisasian

• section string

  Untuk diagram dengan banyak opsi, label untuk bagian tempat opsi harus muncul. UI akan mengelompokkan opsi berdasarkan nilai section-nya. Jika hanya ada satu bagian, UI bagian tidak akan ditampilkan.

  Jika Anda menggunakan section, opsi ini harus ditetapkan di setiap opsi.

• order number

  Angka yang mewakili urutan opsi untuk presentasi di UI. Jika ditentukan, opsi akan diurutkan sesuai dengan urutan ini.

• display_size string

  Class ukuran yang merepresentasikan lebar opsi di UI. Misalnya, jika Anda ingin menampilkan opsi "Minimum" dan "Maksimum" secara berdampingan, Anda dapat menetapkan ukuran tampilan masing-masing ke half.

  Nilai yang Diizinkan: normal (default), half, third

Acara

Peristiwa dapat dipicu oleh diagram (biasanya sebagai respons terhadap interaksi pengguna) yang dapat memperbarui properti visualisasi atau kueri.

Peristiwa ini dapat dipicu dengan memanggil fungsi trigger pada objek visualisasi. Parameter pertama selalu berupa nama peristiwa dan parameter kedua adalah array argumen.

this.trigger("limit", [20]);

Peristiwa yang tersedia

• updateConfig

  Memperbarui setelan konfigurasi saat ini pada diagram.

  Argumen: objek yang berisi kunci konfigurasi yang akan diupdate. Kunci yang tidak ditentukan tidak akan diubah.

  Contoh:

  var vis = this;
  $(element).find(".axis").click(function(){
      vis.trigger("updateConfig", [{axis_hidden: true}]);
  });
  

• limit

  Perbarui batas kueri yang mendasarinya:

  Argumen: bilangan bulat yang mewakili batas baru untuk kueri.

  var vis = this;
  $(element).find(".show-all").click(function(){
      vis.trigger("limit", [500]);
  });
  

• filter

  Perbarui nilai filter pada kueri pokok:

  var vis = this;
  $(element).find(".show-all-tommys").click(function(){
      vis.trigger("filter", [{
          field: "users.name", // the name of the field to filter
          value: "%tommy%", // the "advanced syntax" for the filter
          run: true, // whether to re-run the query with the new filter
      }]);
  });
  

• loadingStart

  Tandai visualisasi sebagai sedang dimuat. Sering kali hal ini tidak diperlukan, tetapi jika visualisasi Anda memuat objek dari lokasi jarak jauh atau melakukan penghitungan yang lama, Anda dapat menggunakannya untuk terus menampilkan indikator pemuatan.

  Halaman akan muncul saat memuat hingga loadingEnd dipicu.

• loadingEnd

  Tandai visualisasi sebagai tidak lagi dimuat.

• printSize (Looker 26.0+)

  Memungkinkan visualisasi memanfaatkan opsi "Luaskan tabel untuk menampilkan semua baris" saat merender dasbor ke PDF. Dengan menggunakan peristiwa ini, aplikasi dapat mengetahui tinggi konten yang dirender dan dapat memperluas ubin dasbor dengan tepat sehingga semua informasi terlihat untuk dicetak.

    this.trigger('printSize', {
      heightExpanded: FULL_HEIGHT_IN_PIXELS
    });
  

• registerOptions (Looker 5.24+)

  Memungkinkan visualisasi mendaftarkan opsi tambahan setelah visualisasi didaftarkan:

    update: function(data, element, config, queryResponse, details){
      options = {}
      // Create an option for each measure in your query
      queryResponse.fields.measure_like.forEach(function(field) {
        id = "color_" + field.name
        options[id] =
        {
      label: field.label_short + " Color",
      default: "#8B7DA8",
      section: "Style",
      type: "string",
      display: "color"
        }
      })
      this.trigger('registerOptions', options) // register options with parent page to update visConfig
      ...
    }
  });