Widget penelusuran memberikan antarmuka penelusuran yang dapat disesuaikan untuk aplikasi web. Widget hanya membutuhkan sejumlah kecil HTML dan JavaScript untuk menerapkan dan mengaktifkan fitur penelusuran umum seperti faset dan penomoran halaman. Anda juga dapat menyesuaikan bagian antarmuka dengan CSS dan JavaScript.
Jika Anda membutuhkan lebih banyak fleksibilitas, selain yang ditawarkan oleh widget, pertimbangkan untuk menggunakan Query API. Untuk mengetahui informasi tentang cara membuat antarmuka penelusuran dengan Query API, lihat Membuat antarmuka penelusuran dengan Query API.
Membuat antarmuka penelusuran
Membuat antarmuka penelusuran memerlukan beberapa langkah:
- Mengonfigurasi aplikasi penelusuran
- Membuat ID klien untuk aplikasi
- Menambahkan markup HTML untuk kotak dan hasil penelusuran
- Memuat widget di halaman
- Menginisialisasi widget
Mengonfigurasi aplikasi penelusuran
Setiap antarmuka penelusuran harus memiliki aplikasi penelusuran yang ditentukan di konsol admin. Aplikasi penelusuran memberikan informasi informasi untuk kueri, seperti sumber data, faset, dan setelan kualitas penelusuran.
Untuk membuat aplikasi penelusuran, lihat Buat pengalaman penelusuran kustom.
Membuat ID klien untuk aplikasi
Selain langkah-langkah dalam Konfigurasikan akses ke Google Cloud Search API, Anda juga harus membuat ID klien untuk aplikasi web.
Saat mengonfigurasi project:
- Pilih jenis klien Browser web
- Berikan URI asal aplikasi Anda.
- Catat ID klien yang telah dibuat. Anda memerlukan ID klien untuk menyelesaikan langkah berikutnya. Rahasia klien tidak diperlukan untuk widget.
Untuk informasi tambahan, lihat OAuth 2.0 untuk Aplikasi Web Sisi Klien.
Menambahkan markup HTML
Widget membutuhkan sejumlah kecil HTML agar berfungsi. Anda harus menyediakan:
- Elemen
input
untuk kotak penelusuran. - Elemen untuk mengaitkan pop-up saran.
- Elemen untuk memuat hasil penelusuran.
- (Opsional) Elemen untuk memuat kontrol faset.
Cuplikan HTML berikut menampilkan HTML untuk widget penelusuran, dengan
elemen yang akan terikat diidentifikasi oleh atribut id
-nya:
Memuat widget
Widget dimuat secara dinamis melalui skrip pemuat. Untuk menyertakan
loader, gunakan tag <script>
seperti yang ditunjukkan:
Anda harus memberikan callback onload
dalam tag skrip. Fungsi ini dipanggil saat pemuat sudah siap. Setelah loader siap, lanjutkan pemuatan widget
dengan memanggil gapi.load()
untuk memuat modul klien API, Login dengan Google, dan Cloud Search.
Fungsi initializeApp()
dipanggil setelah semua modul
dimuat.
Menginisialisasi widget
Pertama, inisialisasi library klien dengan memanggil
gapi.client.init()
atau gapi.auth2.init()
dengan client ID yang Anda buat
dan cakupan https://www.googleapis.com/auth/cloud_search.query
. Selanjutnya, gunakan
gapi.cloudsearch.widget.resultscontainer.Builder
dan
Class gapi.cloudsearch.widget.searchbox.Builder
untuk mengonfigurasi widget
dan mengikatnya ke elemen HTML Anda.
Contoh berikut menunjukkan cara menginisialisasi widget:
Contoh di atas merujuk pada dua variabel untuk konfigurasi yang ditentukan sebagai:
Menyesuaikan pengalaman login
Secara default, widget akan meminta pengguna untuk login dan mengotorisasi aplikasi saat mereka mulai mengetik kueri. Anda dapat menggunakan Login dengan Google untuk Situs untuk menawarkan pengalaman login yang lebih disesuaikan bagi pengguna.
Mengotorisasi pengguna secara langsung
Gunakan Login Dengan Google untuk memantau status login pengguna
pengguna dan {i>login<i} atau {i>log out<i} sesuai kebutuhan. Misalnya,
contoh mengamati isSignedIn
status untuk memantau perubahan login dan
menggunakan GoogleAuth.signIn()
untuk memulai login dari tombol
klik:
Untuk mengetahui detail tambahan, lihat Login dengan Google.
Membuat pengguna login secara otomatis
Anda dapat menyederhanakan pengalaman login lebih jauh dengan mengotorisasi aplikasi terlebih dahulu atas nama pengguna di organisasi Anda. Teknik ini juga berguna jika menggunakan Cloud Identity Aware Proxy untuk menjaga keamanan aplikasi.
Untuk informasi tambahan, lihat Menggunakan Login dengan Google dengan Aplikasi IT.
Menyesuaikan antarmuka
Anda dapat mengubah tampilan antarmuka penelusuran melalui gabungan teknik:
- Mengganti gaya dengan CSS
- Mendekorasi elemen dengan adaptor
- Membuat elemen kustom dengan adaptor
Mengganti gaya dengan CSS
Widget penelusuran dilengkapi dengan CSS-nya sendiri untuk memberi gaya pada saran dan elemen hasil serta kontrol penomoran halaman. Anda dapat mengatur ulang gaya pada elemen tersebut sesuai kebutuhan.
Selama pemuatan, widget penelusuran secara dinamis memuat lembar gaya defaultnya. Proses ini terjadi setelah lembar gaya aplikasi dimuat, sehingga meningkatkan prioritas aturan. Untuk memastikan gaya Anda lebih diprioritaskan daripada gaya default, gunakan pemilih ancestor untuk meningkatkan kekhususan aturan default.
Misalnya, aturan berikut tidak berpengaruh jika dimuat di instance
Tag link
atau style
dalam dokumen.
.cloudsearch_suggestion_container {
font-size: 14px;
}
Sebagai gantinya, kualifikasi aturan dengan ID atau class container ancestor yang dinyatakan di halaman.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
Untuk daftar class dukungan dan contoh HTML yang dihasilkan oleh widget, lihat referensi Class CSS yang didukung.
Mendekorasi elemen dengan adaptor
Untuk mendekorasi elemen sebelum rendering, buat dan tulis ulang
yang mengimplementasikan salah satu metode dekorasi seperti
decorateSuggestionElement
atau decorateSearchResultElement.
Misalnya, adaptor berikut menambahkan class kustom ke elemen saran dan hasil.
Untuk mendaftarkan adaptor saat menginisialisasi widget, gunakan setAdapter()
dari class Builder
masing-masing:
Dekorator dapat mengubah atribut elemen container serta elemen turunan. Elemen turunan dapat ditambahkan atau dihapus selama proses dekorasi. Namun, jika membuat perubahan struktural pada elemen, pertimbangkan untuk membuat elemen secara langsung, bukan dengan menambahkan dekorasi.
Membuat elemen kustom dengan adaptor
Untuk membuat elemen kustom bagi saran, penampung faset, atau hasil penelusuran,
membuat dan mendaftarkan
adaptor yang mengimplementasikan
createSuggestionElement
,
createFacetResultElement
,
atau createSearchResultElement
repetitif.
Adaptor berikut menggambarkan pembuatan saran kustom dan hasil penelusuran
menggunakan tag <template>
HTML.
Untuk mendaftarkan adaptor saat menginisialisasi widget, gunakan setAdapter()
dari class Builder
masing-masing:
Membuat elemen faset kustom dengan createFacetResultElement
tunduk pada beberapa batasan:
- Anda harus melampirkan class CSS
cloudsearch_facet_bucket_clickable
ke yang diklik pengguna untuk mengaktifkan/menonaktifkan bucket. - Anda harus menggabungkan setiap bucket dalam elemen penampung dengan CSS
kelas
cloudsearch_facet_bucket_container
. - Anda tidak dapat merender bucket dalam urutan yang berbeda dari yang muncul di respons.
Misalnya, cuplikan berikut merender faset menggunakan link, bukan kotak centang.
Menyesuaikan perilaku penelusuran
Setelan aplikasi penelusuran mewakili konfigurasi default untuk antarmuka penelusuran dan bersifat statis. Untuk menerapkan filter atau faset dinamis, seperti mengizinkan pengguna untuk beralih sumber data, Anda dapat mengganti setelan aplikasi penelusuran dengan menghalangi permintaan penelusuran menggunakan adaptor.
Implementasikan adaptor dengan
interceptSearchRequest
untuk mengubah permintaan yang dibuat ke
search API
sebelum dieksekusi.
Misalnya, adaptor berikut menghalangi permintaan untuk membatasi kueri ke sumber yang dipilih pengguna:
Untuk mendaftarkan adaptor saat menginisialisasi widget, gunakan
setAdapter()
saat membangun ResultsContainer
HTML berikut digunakan untuk menampilkan kotak centang guna memfilter berdasarkan sumber:
Kode berikut mendeteksi perubahan, menetapkan pilihan, dan mengeksekusi ulang kueri jika diperlukan.
Anda juga dapat menangkap respons penelusuran dengan menerapkan
interceptSearchResponse
pada adaptor.
Menyematkan versi API
Secara default, widget menggunakan API versi stabil terbaru. Untuk mengunci
versi tertentu, tetapkan parameter konfigurasi cloudsearch.config/apiVersion
ke versi yang diinginkan sebelum melakukan inisialisasi widget.
Versi API akan ditetapkan ke 1.0 secara default jika tidak ditetapkan, atau ditetapkan ke nilai yang tidak valid.
Menyematkan versi widget
Untuk menghindari perubahan yang tidak diharapkan pada antarmuka penelusuran, atur
Parameter konfigurasi cloudsearch.config/clientVersion
seperti yang ditunjukkan di bawah ini:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
Versi widget akan ditetapkan ke 1.0 secara default jika tidak ditetapkan, atau ditetapkan ke nilai yang tidak valid.
Mengamankan antarmuka penelusuran
Hasil penelusuran berisi informasi yang sangat sensitif. Ikuti praktik terbaik untuk mengamankan aplikasi web, khususnya terhadap serangan clickjacking.
Untuk mengetahui informasi selengkapnya, lihat Project Panduan OWASP
Mengaktifkan proses debug
Gunakan interceptSearchRequest
mengaktifkan proses debug untuk widget penelusuran. Contoh:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;