/ Search

Android library designed to simplify the process of implementing search-related functionality

Android library designed to simplify the process of implementing search-related functionality

PersistentSearchView

Android library designed to simplify the process of implementing search-related functionality.

Getting Started

  1. Make sure that you've added the jcenter() repository to your top-level build.gradle file.
buildscript {
    //...
    repositories {
        //...
        jcenter()
    }
    //...
}
  1. Add the library dependency to your module-level build.gradle file.
ext {
    //...
    psvVersion = "1.0.0"
}

dependencies {
    //...
    implementation "com.paulrybitskyi.persistentsearchview:persistentsearchview:$psvVersion"
}
  1. Enable the jetifier and androidX support in the top-level gradle.properties file.
//...
android.enableJetifier=true
android.useAndroidX=true
//....
  1. Update your compileSdkVersion in the module-level build.gradle file to 28+.
//...
android {
    //...
    compileSdkVersion 28
    //...
}
//...
  1. Update your com.android.support.appcompat.* dependency to the new androidx.appcompat.* alternative.
//...
dependencies {
    //...
    implementation "androidx.appcompat:appcompat:1.0.0-beta01"
    //...
}
//...
  1. Proceed with the implementation of your own search view.

Basic Implementation

Implementation of a PersistentSearchView with basic functionality involves 2 main steps - declaring a widget inside the XML file of your choice and configuring it in one of the Java/Kotlin classes.

Let's implement a PersistentSearchView with basic functionality by following the steps listed above:

  1. Declaring a widget inside the XML file.

    XML (click to expand)

    <?xml version="1.0" encoding="utf-8"?>
    <RelativeLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto"
        android:layout_width="match_parent"
        android:layout_height="match_parent">
    
        <!-- Other widgets here -->
    
        <com.paulrybitskyi.persistentsearchview.PersistentSearchView
            android:id="@+id/persistentSearchView"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:paddingTop="4dp"
            android:paddingLeft="4dp"
            android:paddingStart="4dp"
            android:paddingRight="4dp"
            android:paddingEnd="4dp"/>
    
    </RelativeLayout>
    

  2. Configuring the widget in one of the Java/Kotlin classes.

    Kotlin (click to expand)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.demo_activity_layout)
    
        //...
    
        with(persistentSearchView) {
            setOnLeftBtnClickListener {
                // Handle the left button click
            }
            setOnClearInputBtnClickListener {
                // Handle the clear input button click
            }
    
            // Setting a delegate for the voice recognition input
            setVoiceRecognitionDelegate(VoiceRecognitionDelegate([email protected]))
    
            setOnSearchConfirmedListener { searchView, query ->
                // Handle a search confirmation. This is the place where you'd
                // want to perform a search against your data provider.
            }
    
            // Disabling the suggestions since they are unused in
            // the simple implementation
            setSuggestionsDisabled(true)
        }
    }
    
    
    //...
    
    
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
    
        // Calling the voice recognition delegate to properly handle voice input results
        VoiceRecognitionDelegate.handleResult(persistentSearchView, requestCode, resultCode, data)
    }
    

    Java (click to expand)

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.demo_activity_layout);
    
        //...
    
        persistentSearchView.setOnLeftBtnClickListener(new OnClickListener() {
    
            @Override
            public void onClick(View view) {
                // Handle the left button click
            }
    
        });
    
        persistentSearchView.setOnClearInputBtnClickListener(new OnClickListener() {
    
            @Override
            public void onClick(View view) {
                // Handle the clear input button click
            }
    
        });
    
        // Setting a delegate for the voice recognition input
        persistentSearchView.setVoiceRecognitionDelegate(new VoiceRecognitionDelegate(this));
    
        persistentSearchView.setOnSearchConfirmedListener(new OnSearchConfirmedListener() {
    
            @Override
            public void onSearchConfirmed(PersistentSearchView searchView, String query) {
                // Handle a search confirmation. This is the place where you'd
                // want to perform a search against your data provider.
            }
    
        });
    
        // Disabling the suggestions since they are unused in
        // the simple implementation
        persistentSearchView.setSuggestionsDisabled();
    }
    
    
    //...
    
    
    @Override
    protected fun onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
    
        // Calling the voice recognition delegate to properly handle voice input results
        VoiceRecognitionDelegate.handleResult(persistentSearchView, requestCode, resultCode, data);
    }
    

Basic Recent Suggestions Implementation

Implementation of a PersistentSearchView with recent suggestions is pretty much the same as Basic Implementation with one exception: the view configuration.

In this implementation you'll need to provide a bit more configuration for the widget in order to show recent suggestions to the user, such as providing implementation for a couple of listeners as well as fetching suggestions from your data provider and setting them to the search view.

For example, here is the configuration of the widget with recent suggestions functionality:

Java (click to expand)

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.demo_activity_layout);

    //...

    persistentSearchView.setOnLeftBtnClickListener(new OnClickListener() {
        
        @Override
        public void onClick(View view) {
            // Handle the left button click
        }

    });

    persistentSearchView.setOnClearInputBtnClickListener(new OnClickListener() {
        
        @Override
        public void onClick(View view) {
            // Handle the clear input button click
        }

    });

    // Setting a delegate for the voice recognition input
    persistentSearchView.setVoiceRecognitionDelegate(new VoiceRecognitionDelegate(this));

    persistentSearchView.setOnSearchConfirmedListener(new OnSearchConfirmedListener() {

        @Override
        public void onSearchConfirmed(PersistentSearchView searchView, String query) {
            // Handle a search confirmation. This is the place where you'd
            // want to save a new query and perform a search against your
            // data provider.
        }

    });

    persistentSearchView.setOnSearchQueryChangeListener(new OnSearchQueryChangeListener() {
        
        @Override
        public void onSearchQueryChanged(PersistentSearchView searchView, String oldQuery, String newQuery) {
            // Handle a search query change. This is the place where you'd
            // want load new suggestions based on the newQuery parameter.
        }

    });

    persistentSearchView.setOnSuggestionChangeListener(new OnSuggestionChangeListener() {

        @Override
        public void onSuggestionPicked(SuggestionItem suggestion) {
            // Handle a suggestion pick event. This is the place where you'd
            // want to perform a search against your data provider.
        }

        @Override
        public void onSuggestionRemoved(SuggestionItem suggestion) {
            // Handle a suggestion remove event. This is the place where
            // you'd want to remove the suggestion from your data provider.
        }

    });
}
	

//...


@Override
public void onResume() {
    super.onResume();

    List<String> searchQueries = null;

    // Fetching the search queries from the data provider
    if(persistentSearchView.isInputQueryEmpty) {
        searchQueries = mDataProvider.getInitialSearchQueries();
    } else {
        searchQueries = mDataProvider.getSuggestionsForQuery(persistentSearchView.inputQuery);
    }

    // Converting them to recent suggestions and setting them to the widget
    persistentSearchView.setSuggestions(SuggestionCreationUtil.asRecentSearchSuggestions(searchQueries), false);
}

	
//...


@Override
protected fun onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);

    // Calling the voice recognition delegate to properly handle voice input results
    VoiceRecognitionDelegate.handleResult(persistentSearchView, requestCode, resultCode, data);
}

Kotlin (click to expand)

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

    //...

    with(persistentSearchView) {
        setOnLeftBtnClickListener {
            // Handle the left button click
        }
        setOnClearInputBtnClickListener {
            // Handle the clear input button click
        }

        // Setting a delegate for the voice recognition input
        setVoiceRecognitionDelegate(VoiceRecognitionDelegate([email protected]))

        setOnSearchConfirmedListener { searchView, query ->
            // Handle a search confirmation. This is the place where you'd
            // want to save a new query and perform a search against your
            // data provider.
        }

        setOnSearchQueryChangeListener { searchView, oldQuery, newQuery ->
            // Handle a search query change. This is the place where you'd
            // want load new suggestions based on the newQuery parameter.
        }

        setOnSuggestionChangeListener(object : OnSuggestionChangeListener {

            override fun onSuggestionPicked(suggestion: SuggestionItem) {
                // Handle a suggestion pick event. This is the place where you'd
                // want to perform a search against your data provider.
            }

            override fun onSuggestionRemoved(suggestion: SuggestionItem) {
                // Handle a suggestion remove event. This is the place where
                // you'd want to remove the suggestion from your data provider.
            }

        })
    }
}


//...


override fun onResume() {
    super.onResume()

    // Fetching the search queries from the data provider
    val searchQueries = if(persistentSearchView.isInputQueryEmpty) {
        mDataProvider.getInitialSearchQueries()
    } else {
        mDataProvider.getSuggestionsForQuery(persistentSearchView.inputQuery)
    }

    // Converting them to recent suggestions and setting them to the widget
    persistentSearchView.setSuggestions(SuggestionCreationUtil.asRecentSearchSuggestions(searchQueries), false)
}


//...


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    // Calling the voice recognition delegate to properly handle voice input results
    VoiceRecognitionDelegate.handleResult(persistentSearchView, requestCode, resultCode, data)
}

Basic Regular Suggestions Implementation

Implementation of a PersistentSearchView with regular suggestions is identical to the Basic Recent Suggestions Implementation with one exception: suggestions creation method asRecentSearchSuggestions(searchQueries) should be replaced with asRegularSearchSuggestions(searchQueries).

Advanced Use

See the Sample app.

Difference between recent and regular suggestions

The difference between recent and regular suggestions is that a user can remove recent suggestions from the list while regular suggestions cannot be removed (there is no remove button on the regular suggestions).

For example, here are screenshots of recent suggestions compared to regular:

Recent Regular

GitHub