Skip to content

Latest commit

 

History

History
98 lines (72 loc) · 4.26 KB

README.md

File metadata and controls

98 lines (72 loc) · 4.26 KB
Raw

cordova-search-bar

A Cordova plugin to display a native SearchBar and send the search text back to the Cordova WebView. For iOS, this means a simple usage of the UISearchBar. For Android, this is an EditText with a colored border and added search icon (uses internal Android resource, so icon appearance may very).

Installation

Follow the Cordova guide on plugin installation http://cordova.apache.org/blog/releases/2013/07/23/cordova-3

Use cordova.searchbar to call the native methods (eg. cordova.searchbar.show()).

or

Install Manually

  1. Copy the SearchBar.h and SearchBar.m files into your XCode project /Plugins directory.
  2. Copy searchbar.js into your XCode project /www directory (can place anywhere in this directory, eg. www/js).
  3. Add the following to the config.xml in your root XCode project directory: <feature name="SearchBar"> <param name="ios-package" value="SearchBar" /> </feature>
  4. Import searchbar.js wherever needed in your HTML (path being wherever you placed the file in step 2).
  5. Use the SearchBar variable to call the defined methods (Manual install only. Plugman install maps this variable to cordova.searchbar).

Methods

show()
Slides-in the native UISearchBar onto the top of the screen.

hide()
Slides-out the native UISearchBar.

showNavigation()
iOS Only
Slides-in the native UISearchBar within UINavigationBar. Will look the same as show() until push() is called (see below), which will add a native "Back" button to the left of the UISearchBar. DO NOT USE CONCURRENTLY WITH show()/hide().

hideNavigation()
iOS Only
Slides-out the native UISearchBar & UINavigationBar. DO NOT USE CONCURRENTLY WITH show()/hide().

push()
iOS Only
Pushes another navigation item onto the stack. Call after navigating to a new page in the WebView. After being called the first time, a back button will appear. If the back button is clicked, the Cordova WebView wil perform go back a page. DO NOT USE CONCURRENTLY WITH show()/hide().

pop()
iOS Only
Removes the top navigation item off of the stack. If the last item is removed, the back button will disappear. DO NOT USE CONCURRENTLY WITH show()/hide().

Handling User Input

When a user enters a search term into the UISearchBar and presses the native "Search" button, the native code looks to fire a JavaScript event named searchEvent. The native code will send an Object with one key/value pair of key "text" (value is the search String entered by the user) to the function associated with this event.
You must add a JavaScript event listener with the name 'searchEvent' in order to retrieve the search value.

Example:

function mySearchEventFunction(data) {
    // Your logic here
    alert("You searched: " + data.text);  
}  
document.addEventListener('searchEvent', mySearchEventFunction, true);

Customization

iOS
You may customize the native UISearchBar functionality in any way by editing the SearchBar.h and SearchBar.m files.
SearchBar.m comes with the following constants allowing for quick and easy customization.

double ANIMATION_DURATION
Duration of the slide animations. Increase the value to slow the animation.

BOOL RESIZE_WEBVIEW
Determines if Cordova WebView should "shrink" underneith the SearchBar.
Default is YES, Set to NO to overlay SearchBar atop the WebView.

BOOL OFFSET_IOS7
Determines if we should offset the top of the view when device is at or above iOS7.
Default is YES, Set to NO to use fullscreen.

BOOL ALLOW_EMPTY_SEARCH
Determines if user is allowed to hit the "Search" button if they have NOT entered data.
Default is YES, Set to NO to ensure user has entered at least one character before search.

Android
You may customize the native EditText functionality in any way by editing the SearchBar.java Class.