QueryBox allows you to easily create a Live Search Input form that lets users search and refine a query while continuously showing all valid results as they type.
The widget is built on top of the Dojo javascript framework.
Demos
Features
- keyboard input you can use your keyboard up / down keys to navigate the results. esc will close the dropdown, enter submits the current selection.
- delayed query submission queries are only sent to the server after a determined ammount of time after user has stopped typing..
- can handle categorized results results can be a plain list, or a categorized one.
- customizable results markup simply overwrite the getItemMarkup or getResultsMarkup methods to return your own customized markup.
How to use
QueryBox requires Dojo (Base) 1.2.2
To use, all you need is the following:
import dojo into your project
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/dojo/1.2.0/dojo/dojo.xd.js"></script>
import marumushi.widget.querybox.js into your project
<script type="text/javascript" src="js/marumushi.widget.querybox.js"></script>
import the querybox.css stylesheet
<link rel="stylesheet" type="text/css" href="css/querybox.css" />
create a holder div where querybox will be rendered, give it a unique ID:
<div id="qbox"></div>
create a querybox instance passing the query URL and the id of the div where to render it:
var queryBox = new marumushi.widget.QueryBox("tests/search.php?q=","qbox");
your project should look like this:
<html>
<head>
<link rel="stylesheet" type="text/css" href="css/querybox.css" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/dojo/1.2.0/dojo/dojo.xd.js"></script>
<script type="text/javascript" src="js/marumushi.widget.querybox.js"></script>
<script type="text/javascript">
//<![CDATA[
var queryBox = new marumushi.widget.QueryBox("tests/search.php?q=","qbox"); //<-- thats it!
//]]>
</script>
<head>
<body>
<div class="qbox"><!--- querybox will be rendered here ---></div>
</body>
</html>
Styling
You can simply use the included querybox.css stylesheet or create your own.
If you wanted to use a different class for your qbox other than the one in querybox.css, simply overrite the cssClass property of your querybox instance.
var queryBox = new marumushi.widget.QueryBox("tests/search.php?q=","qbox");
queryBox.cssClass = 'myCssClass';
Else you can always fiddle around in the css stylesheet.
Integrating with your Server
To return results to QueryBox, you will need a serverside script that can return resultsin JSON format.
For example provided of a script "search.php" that takes a param "q":
the request:
search.php?q=fruits
the results:
{results:[
{"title":"apples","link":"apples.php","description":"apples are awesome yah","id":"0","category":"ok fruits"},
{"title":"bananas","link":"bananas.php","description":"bananas are kinda ok","id":"1","category":"ok fruits"},
{"title":"tomatoes","link":"tomato.php","description":"tomatoes are very ok","id":"2","category":"awesome fruits"},
{"title":"watermelom","link":"link":"watermelon.php","description":"whattam","id":"3","category":"awesome fruits"},
{"title":"starfruit","link":"link":"starfruit.php","description":"not sweet","id":"4","category":"rare fruits"},
{"title":"oranges","link":"oranges.php","description":"are boring but yummy","id":"5","category":"boring fruits"},
{"title":"lemons","link":"lemons.php","description":"are better than limes.","id":"6","category":"boring fruits"},
{"title":"limes","link":"limes.php","description":"limes are for margaritas","id":"7","category":"ok fruits"},
{"title":"pears","link":"pears.php","description":"rock when you bake them.","id":"8","category":"awesome fruits"},
{"title":"kiwi","link":"kiwi.php","description":"is the new pink in fruits.","id":"9","category":"awesome fruits"}
]}
PHP Only (Just for the kicks)
To get any of the following 2 demos working you will need to go ahead and download the following csv file from the census.gov website.
http://www.census.gov/popest/cities/files/SUB-EST2005-all.csv ( 7mb dowbload ).
drop this file in the /data folder of your project in your server
Included in the download is a PHP script class.queryboxcsv.php containing a class that can be simply instantiated and used like this:
require 'includes/class.queryboxcsv.php';
$search_query = !empty($_GET['q']) ? $_GET['q'] : null;
$search = new QueryBoxCSV();
if($search_query){
echo $search->query($search_query);
}
Please keep in mind that that specific demo should never be tried to be run in a production server.
Everytime a user types something in querybox this script will run, will read the 6.5 Megabyte csv file in Memory, do some really slow string match and output the results. Ideally you want to do this by having all the data stored in a database and querying properlly there.
Take a look at the following demo, since that's really the way you want to go. It takes a little bit more time to setup, but it will be many many times more efficient
PHP + MYSQL
Also included in the download is a PHP script class.queryboxdb.php containing a class that can be simply instantiated and used like this:
require 'includes/class.queryboxdb.php';
$search_query = !empty($_GET['q']) ? $_GET['q'] : null;
$search = new QueryBoxDB();
if($search_query){
//create the query to your DB, and serve the Json Results:
$search->query($search_query);
$search->serve();
}
Of course in there you will need to modify the query method to adapt to your own datasource.
License
This work is licensed under a Creative Commons Attribution 3.0 Unported License.
You are free:
- to Share— to copy, distribute and transmit the work
- to Remix— to adapt the work
Under the following conditions:
- For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page.
- Any of the above conditions can be waived if you get permission from the copyright holder.
- Nothing in this license impairs or restricts the author's moral rights.
Updates
- Sat Nov 29, 2008 - posted!
Contact
Any questions, comments, ideas drop me a line at marcos@marumushi.com