Menambahkan Saran Kueri Terbaru

Saat menggunakan dialog penelusuran atau widget penelusuran Android, Anda dapat memberikan saran penelusuran berdasarkan kueri penelusuran terbaru. Misalnya, jika sebelumnya pengguna menelusuri "anak anjing", maka kueri tersebut akan ditampilkan sebagai saran saat dia mulai mengetik kueri yang sama. Gambar 1 menunjukkan contoh dialog penelusuran dengan saran kueri terbaru.

Sebelum memulai, Anda perlu menerapkan dialog penelusuran atau widget penelusuran untuk penelusuran dasar dalam aplikasi Anda. Jika belum melakukannya, lihat Membuat Antarmuka Penelusuran.

Dasar-Dasar

Gambar 1. Screenshot dialog penelusuran dengan saran kueri terbaru.

Saran kueri terbaru sebenarnya adalah penelusuran tersimpan. Saat pengguna memilih salah satu saran, aktivitas penelusuran Anda akan menerima intent ACTION_SEARCH dengan saran tersebut sebagai kueri penelusurannya, yang telah ditangani oleh aktivitas penelusuran Anda (seperti dijelaskan dalam Membuat Antarmuka Penelusuran).

Untuk memberikan saran kueri terbaru, Anda perlu:

• Menerapkan aktivitas penelusuran, seperti yang dijelaskan dalam Membuat Antarmuka Penelusuran.
• Membuat penyedia konten yang memperluas SearchRecentSuggestionsProvider dan mendeklarasikannya dalam manifes aplikasi Anda.
• Memodifikasi konfigurasi penelusuran dengan informasi tentang penyedia konten yang menyediakan saran penelusuran.
• Menyimpan kueri ke penyedia konten setiap kali penelusuran dijalankan.

Selain menampilkan dialog penelusuran, sistem Android juga menampilkan saran penelusuran di bawah dialog atau widget penelusuran. Yang perlu Anda lakukan hanyalah menyediakan sumber dari mana sistem dapat mengambil saran.

Setelah sistem mengidentifikasi bahwa aktivitas Anda adalah aktivitas penelusuran dan memberikan saran penelusuran, prosedur berikut akan terjadi segera setelah pengguna mulai mengetikkan kueri:

1. Sistem mengambil teks kueri penelusuran (apa pun yang telah diketikkan sejauh ini) dan mengirimkan kueri ke penyedia konten yang menampung saran Anda.
2. Penyedia konten akan menampilkan Cursor yang mengarah ke semua saran yang cocok dengan teks kueri penelusuran.
3. Sistem menampilkan daftar saran yang disediakan oleh Cursor.

Setelah saran kueri terbaru ditampilkan, berikut ini dapat terjadi:

• Jika pengguna mengetik tombol lain, atau mengubah kueri dengan cara apa pun, langkah di atas akan diulang dan daftar saran akan diperbarui.
• Jika pengguna menjalankan penelusuran itu, saran akan diabaikan dan penelusuran akan dikirim ke aktivitas penelusuran Anda menggunakan intent ACTION_SEARCH normal.
• Jika pengguna memilih sebuah saran, intent ACTION_SEARCH akan dikirim ke aktivitas penelusuran Anda menggunakan teks yang disarankan sebagai kueri.

Class SearchRecentSuggestionsProvider yang Anda perluas untuk penyedia konten Anda menangani tugas yang dijelaskan di atas secara otomatis, jadi sebenarnya sangat sedikit kode yang perlu ditulis.

Membuat Penyedia Konten

Penyedia konten yang Anda perlukan untuk saran kueri terbaru haruslah implementasi dari SearchRecentSuggestionsProvider. Class ini melakukan nyaris semuanya untuk Anda. Yang perlu Anda lakukan hanyalah menulis constructor class yang mengeksekusi satu baris kode.

Misalnya, berikut adalah implementasi lengkap penyedia konten untuk saran kueri terbaru:

    class MySuggestionProvider : SearchRecentSuggestionsProvider() {
        init {
            setupSuggestions(AUTHORITY, MODE)
        }

        companion object {
            const val AUTHORITY = "com.example.MySuggestionProvider"
            const val MODE: Int = SearchRecentSuggestionsProvider.DATABASE_MODE_QUERIES
        }
    }
    

    public class MySuggestionProvider extends SearchRecentSuggestionsProvider {
        public final static String AUTHORITY = "com.example.MySuggestionProvider";
        public final static int MODE = DATABASE_MODE_QUERIES;

        public MySuggestionProvider() {
            setupSuggestions(AUTHORITY, MODE);
        }
    }
    

Panggilan ke setupSuggestions() meneruskan nama otoritas penelusuran dan mode database. Otoritas penelusuran dapat berupa string unik apa pun, tetapi praktik terbaiknya adalah menggunakan nama yang sepenuhnya memenuhi syarat untuk penyedia konten Anda (nama paket diikuti dengan nama class penyedia; misalnya "com.example.MySuggestionProvider"). Mode database harus menyertakan DATABASE_MODE_QUERIES dan, jika diinginkan, dapat menyertakan DATABASE_MODE_2LINES, yang menambahkan kolom lain ke tabel saran agar Anda dapat menyediakan baris teks kedua bersama setiap saran. Misalnya, jika Anda ingin memberikan dua baris di setiap saran:

    const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES
    

    public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;
    

Sekarang, deklarasikan penyedia konten dalam manifes aplikasi Anda menggunakan string otoritas yang sama dengan yang digunakan di class SearchRecentSuggestionsProvider Anda (serta dalam konfigurasi penelusuran). Contoh:

    <application>
        <provider android:name=".MySuggestionProvider"
                  android:authorities="com.example.MySuggestionProvider" />
        ...
    </application>
    

Memodifikasi Konfigurasi Penelusuran

Untuk mengonfigurasi sistem agar menggunakan penyedia saran, Anda perlu menambahkan atribut android:searchSuggestAuthority dan android:searchSuggestSelection ke elemen <searchable> dalam file konfigurasi penelusuran Anda. Contoh:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MySuggestionProvider"
        android:searchSuggestSelection=" ?" >
    </searchable>
    

Nilai untuk android:searchSuggestAuthority harus berupa nama yang sepenuhnya memenuhi syarat bagi penyedia konten Anda, yang sama persis dengan otoritas yang digunakan di penyedia konten (string AUTHORITY dalam contoh di atas).

Nilai untuk android:searchSuggestSelection harus berupa tanda tanya tunggal, didahului dengan spasi (" ?"), yang merupakan placeholder untuk argumen pemilihan SQLite (yang otomatis diganti oleh teks kueri yang dimasukkan oleh pengguna).

Menyimpan Kueri

Untuk mengisi kumpulan kueri terbaru, tambahkan setiap kueri yang diterima oleh aktivitas penelusuran Anda ke SearchRecentSuggestionsProvider. Caranya, buatlah instance SearchRecentSuggestions dan panggil saveRecentQuery() setiap kali aktivitas penelusuran Anda menerima kueri. Misalnya, berikut adalah cara menyimpan kueri selama metode onCreate() aktivitas Anda:

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main)

        if (Intent.ACTION_SEARCH == intent.action) {
            intent.getStringExtra(SearchManager.QUERY)?.also { query ->
                SearchRecentSuggestions(this, MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE)
                        .saveRecentQuery(query, null)
            }
        }
    }
    

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        Intent intent  = getIntent();

        if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
            String query = intent.getStringExtra(SearchManager.QUERY);
            SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
                    MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
            suggestions.saveRecentQuery(query, null);
        }
    }
    

Constructor SearchRecentSuggestionsProvider memerlukan otoritas dan mode database yang sama dengan yang dideklarasikan oleh penyedia konten Anda.

Metode saveRecentQuery() akan mengambil string kueri penelusuran sebagai parameter pertamanya dan, secara opsional, string kedua untuk disertakan sebagai baris kedua saran (atau null). Parameter kedua ini hanya digunakan jika Anda telah mengaktifkan mode dua baris untuk saran penelusuran dengan DATABASE_MODE_2LINES. Jika Anda telah mengaktifkan mode dua baris, maka teks kueri juga akan dicocokkan dengan baris kedua ini saat sistem mencari saran yang cocok.

Menghapus Data Saran

Untuk melindungi privasi pengguna, sebaiknya Anda selalu menyediakan cara bagi pengguna untuk menghapus saran kueri terbaru. Untuk menghapus histori kueri, panggil clearHistory(). Contoh:

    SearchRecentSuggestions(this, HelloSuggestionsProvider.AUTHORITY, HelloSuggestionsProvider.MODE)
            .clearHistory()
    

    SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
            HelloSuggestionProvider.AUTHORITY, HelloSuggestionProvider.MODE);
    suggestions.clearHistory();
    

Jalankan ini dari tombol, item preferensi, atau item menu "Hapus Histori Penelusuran" pilihan Anda. Sebaiknya Anda juga menyediakan dialog konfirmasi untuk memverifikasi bahwa pengguna memang ingin menghapus histori penelusurannya.