After writing a recent blog post about using the search API to offer efficient and widespread navigation, I started thinking about another neat use for the search API, search suggestions.  This may be a misnomer so please allow me to explain.  Search suggestions refer to the dropdown menus under a search box that use ajax to offer realtime search results and commonly eliminate the need to travel to a search results page, ultimately making the search experience faster and generally much more impressive.  Here are some examples.

Apple The Apple website offers what I consider the most elegant search suggestion solution.  They have combined design and function to offer a tool that is easy to understand and thorough enough to cover multiple “departments”.

Google The Google search suggestion solution was actually launched as a full Google product and was kept separate from the standard Google search until recently. While it is not as elegant as the Apple offering it does offer more search results (which is obviously expected) and does eliminate the need to visit the search results page.  They’ve also included relevant advertisements which may be a testament to its success.

Building a MindTouch Search Suggest

Search API

To get started the first thing you need to familiarize yourself with is MindTouch Search API.  Basically all you need to know is how to construct the url.

www.yourmindtouch.com/@api/deki/site/search?limit=5&q=help

Using this url you can quickly access the search API for different terms and limit your result set accordingly.

HTML

In order to get our search suggest working we need to layout some basic HTML.  This HTML includes the search input and the dropdown menu that will later get populated by jQuery.  You must add this HTML to a MindTouch page in source mode. 

<h1>Search Suggestion</h1>
<input type="text" id="search-input">

<div id="search-suggest">
	<a href="#" class="close">x</a>
	<div class="search-pages">
		<strong>pages</strong>
	</div>
	<div class="search-files">
		<strong>files</strong>
	</div>
	<div class="search-comments">
		<strong>comments</strong>
	</div>
</div>

JQuery

Now that you know how to access the API and you have your base HTML you need to connect all the parts.   Again this needs to be entered in source mode .  I’ve added some highlighted comments to walk you through the jquery.

<script type="text/javascript">
	$("body").ready( function() {

                /*Hide the dropdown menu when a user clicks the close button*/
		$("#search-suggest a.close").click( function() {
			$("#search-suggest").hide();
			return false;
		});

                /*Run this function each time the uses pushes a key in the search box*/
  		$("#search-input").keyup( function() {
			if ($(this).val()==''){
				$("#search-suggest").hide();
				return false;
			}
                        /*set q = to the search term*/
			var q = $(this).val();

                    /*Delay the function from executing for 400ms so it doesn't run on every keyup*/
 		    clearTimeout($.data(this, "timer"));
		    var ms = 400; //milliseconds
		    var wait = setTimeout(function() {

                      /*Run the search function with search string q*/
		      loadsearch(q);
		    }, ms);

		    $.data(this, "timer", wait);
		});
	});

function loadsearch(q) {
        /*API url*/
	var qurl="http://developer.mindtouch.com/@api/deki/site/search?limit=10&q="+q;
        /*Count variable to keep track of how many pages, files and comments*/
	var cntpage=0;
	var cntfile=0;
	var cntcomments=0;
        /*Load the search using ajax, return the results in xml variable*/
	jQuery.get(qurl, function(xml) {
                /*Remove the existing links so you can add new content*/
		$("#search-suggest .search-pages a").remove();
		$("#search-suggest .search-files a").remove();
		$("#search-suggest .search-comments a").remove();
		$("#search-suggest .search-comments span").remove();
                /*Use Jquery selectors with XML to find the necessary nodes - Path, Title*/
		$(xml).find('search > page').each(function(){
			var qpath = $(this).find(" > path").text();
			var qtitle = $(this).find("> title").text();
                        /*Add the new search result to the search-pages dropdown*/
		        $("#search-suggest .search-pages ").append('<a class="page" href="/' + qpath + '">' + qtitle.substr(0,30) + '</a>');
			cntpage++;
		});
                /*Use Jquery selectors with XML to find the necessary nodes - Contents, Filename*/
		$(xml).find('search > file').each(function(){
			var quri = $(this).find(" > contents").attr("href");
			var qtitle = $(this).find(" > filename").text();
			$("#search-suggest .search-files").append('<a class="file" href="' + quri + '">' + qtitle + '</a>');
			cntfile++;
		});
                /*Use Jquery selectors with XML to find the necessary nodes - Username, Comment, URI*/
		$(xml).find('search > comment').each(function(){
			var quser = $(this).find("username").text();
			var qcomment = $(this).find(" > content").text();
			var quri = $(this).find("path").text();
			$("#search-suggest .search-comments").append('<a href="/' + quri + '" class="comment-user">' + quser + '</a><span class="comment-text">' + qcomment.substr(0,40) + '...</span>');
			cntcomments++;
		});
                /*If there are no pages, hide the page dropdown*/
		if(cntpage>0){
			$("#search-suggest .search-pages").show();
		}else {
			$("#search-suggest .search-pages").hide();
		}
                /*If there are no files, hide the file dropdown*/
		if(cntfile>0){
			$("#search-suggest .search-files").show();
		}else {
			$("#search-suggest .search-files").hide();
		}
                /*If there are no comments, hide the comment dropdown*/
		if(cntcomments>0){
			$("#search-suggest .search-comments").show();
		}else {
			$("#search-suggest .search-comments").hide();
		}
                /*If there are any results show the appropriate dropdowns*/
		if(cntpage>0 || cntfile>0 || cntcomments>0){
			$("#search-suggest").show();
		}else {
			$("#search-suggest").hide();
		}
	});
}
</script>

CSS

Lastly, once you’ve got it working it needs to look good, otherwise it might not be legible at all.   I’ve put some simple CSS together but feel free customize the look & feel.

<div>
<style>
#search-suggest strong{
	margin:0 0 10px 0;
	color:#999;
	display:block;
}
#search-suggest {
	border:1px solid #ccc;
	display:none;
	padding:0;
	position:absolute;
	overflow:hidden;
	background:#fff;
	font-size:11px;
	min-width:150px;
	z-index:50;
}
#search-suggest .search-pages{
	float:left;
	padding:5px 20px;
	max-width:200px;
}
#search-suggest .search-files{
	float:left;
	padding:5px 20px;
	max-width:200px;
}
#search-suggest .search-comments{
	float:left;
	padding:5px 20px;
	max-width:200px;
}
#search-suggest a {
	display:block;
	padding:0 0 0 20px;
	height:16px;
	overflow:hidden;
	margin:0 0 5px 0;
	background-image:url(/skins/common/icons/icons.gif);
	background-repeat:no-repeat;
}
#search-suggest .search-pages a {
	background-position:0 -768px;

}
#search-suggest .search-files a {
	background-position:0 -1040px;
}
#search-suggest .search-comments .comment-user {
	display:block;
	font-weight:bold;
	margin-bottom:0px;
	padding:0;
}
#search-suggest .search-comments .comment-text {
	display:block;
	font-weight:100;
	margin-bottom:10px;
	color:#999;
}
.no-show {
	display:none;
}
#search-suggest a.close{
	float:right;
	display:block;
	font-size:14px;
	width:15px;
	padding:0 0 1px 0;
	line-height:1;
	-moz-border-radius:7px;
	border:2px solid #fff;
	font-weight:bold;
	text-align:center;
	background:#ccc;
	color:#fff;
	text-decoration:none;
}
#search-suggest .close:hover{
	background:#9f1313;
	text-decoration:none;
	color:#fff;
}
</style>
</div>

MindTouch The MindTouch search suggestion tool cleanly separates pages, files and comments to show you a wide variety of search results.  Additionally it is legible and does eliminate the need to travel to the search results page.

I hope you enjoyed this tutorial

Damien Howley
@DamienH