How to use the Google AJAX Search API on your web site.

The Google AJAX Search API

The Google AJAX Search API is a Javascript library that allows you to embed Google Search in your web pages and other web applications. To use the API, you will first need to sign up for an API key.

The Google AJAX Search API provides simple web objects that perform inline searches over a number of Google services (Web Search, Local Search, Video Search, Blog Search, News Search, Book Search, and Image Search). If your web page is designed to help users create content (e.g. message boards, blogs, etc.), the API is designed to support these activities by allowing them to copy search results directly into their messages.

If so, then why wrap it?

I wrapped the Google API up into a seperate component so that I can use the Google API in more than one web page without having to recreate all of the object over and over again. Most of the setup of the Google API is repetitive across multiple instances of it. The way the Google API was wrapped should all others to use the object with only a small modification. See the Samples section below.

The MyGSearch object

Download the MyGSearch JavaScript and HTML files here.

Properties

Property Name Property Type Purpose Default Value
HideMainContent boolean Indicated whether or not the Main Content should be shown while the search results are visible true
SearchControl google.SearchControl This is a reference to the google.SearchControl null
WatermarkText string This is the text to be displayed as the watermark. The watermark text will be visible if the search input in empty Search for …
IsInitialized boolean Indicates if the MyGSearch is initialized, this value is set after the Initialize function is completed. false
Divs object Contains all of the divs that are used for the MyGSearch object new Object()
CSS object Contains all of the CSS classes used for the MyGSearch object new Object()

 

Divs object

Property Name Property Type Purpose Default Value
SearchResults DOM object (DIV) This is the DIV tag that the Google API will replace the contents with the search results. null
SearchInputBox DOM object (INPUT) This is the INPUT control that the Google API will use to execute searches. null
SearchBranding DOM object (DIV) This is the DIV that the Google API will place the required “powered by Google” branding. null
SearchStarting DOM object (DIV) This is the DIV tag that will be shown while the searching is happening. null
SearchClose DOM object (DIV) This is the DIV tag that will display the “Close Search Results” content. This is used to reset the page back to it’s normal state. null
MainContent DDOM object (DIV) This is the DIV of you main content. This will be hidden while searching, if the HideMainContent property is true until the ClearResults is called. null

CSS Object

Property Name Property Type Purpose Default Value
Watermark string The CSS style to use when the search box input control needs to display the watermark “”
InputBox string The CSS style when the search box input control is being edited or not displaying the watermark “”

Methods

Initialize

Initializes the all of the properties and google.search object.

Parameter Property Type Purpose
resultsDiv DOM object (DOM object) This is where all of the results will be replaced by the Google API. This parameter will update the Divs.SearchResults property.
inputBox DOM object (INPUT type=”text”0 This is the text box that the Google API will hook to execute the searches. This parameter will update the Divs.SearchInputBox property.
brandingDiv DOM object (DIV) This is the div that the Google API will place the required “Powered by Google” branding. This parameter will update the Divs.SearchBranding property.
mainDiv DOM object (DIV) This is the DIV that contains you main content. This DIV will be hidden while searching if the HideMainContent property is set to true. This parameter will update the Divs.MainContent property.
startSearchingDiv DOM object (DIV) This DIV will be displayed while the Google API is executing the search. It will be hidden when the search is complete. This parameter will update the Divs.StartSearching property.
closeDiv DOM object (DIV) This DIV will be displayed after the Google API has completed the search. This DIV allows you to provide a mechanism to close the search results, which can be done by calling the ClearResults methods. This parameter will update the Divs.SearchClose property.

ClearResults

This message performs the following:

  • Clears the search results
  • Hides the Divs.SearchClose DIV
  • Calls the onInputBlur method
  • Hides the Divs.SearchResults DIV
  • Shows the Divs.MainContent DIV
Parameter Property Type Purpose
none

Execute

Executes a Google search based on the value specified in the query parameter.

Parameter Property Type Purpose
query string The value to search google for.

onSearchComplete

This method is called by the Google API when the search is complete. This methods does the following.

  • Hides the SearchStarting DIV
  • Shows the SearchResults DIV
  • Shows the SearchClose DIV
  • Hides or Shows the MainContent DIV based on the value of the HideMainContent property.
Parameter Property Type Purpose
searchControl google.searchControl The Google search control that is calling this method.
searcher google.searcher The Google searcher that is complete.

onStartSearching

This event is raised by the google.search component. In it we will Hide the Main Content and show the SearchStarting Div

Parameter Property Type Purpose
searchControl google.searchControl The Google search control that is calling this method.
searcher google.searcher The Google search that has started searching.
query string The text that is being searched for.

onInputBlur

This mimics the Ajax ASP.NET watermark extender control by changing the CSS class of the input box based on the value of it. This is called when the focus leaves the input box.

Parameter Property Type Purpose
gSearch A MyGSearch object A reference to the myGSearch object that you want to blur.

onInputFocus

This mimics the Ajax ASP.NET watermark extender control by changing the CSS class of the input box based on the value of it. This is called when the input box has focus.

Parameter Property Type Purpose
gSearch A MyGSearch object A reference to the myGSearch object that you want to blur.

Using the MyGSearch object

There are two easy steps to using the MyGSearch objects. This of course assumes that you have obtained a Google API key from //code.google.com/apis/ajaxsearch/signup.html.

Step 1: Create the HTML content

In order for your to use the MyGSearch control you must create 5 DIVs and one input box. The five Divs map to the five Divs object properties, SearchResults, SearchBranding, MainContent, SearchStarting, and SearchClose. The input box will be used for the Google API to execute the search.

The HTML content will exist in two parts, the first the HEAD section

<script src="//www.google.com/jsapi?key=YOUR_KEY_HERE" type="text/javascript"></script>
<script src="MyGSearch.js" type=text/javascript"></script>
<script src="Util.js" type="text/javascript"></script>

Remember to replace YOUR_KEY_HERE with your Google API key. Then in the body of the HTML page you add in the required DIVs and input box.

<div id="divSearchClose">
	<a href="javascript:ClearResults();" id="searchCloseLink">Close Search Results</a>
</div>
<div>
	<input type="text" id="txtSearchInput" />
	<input type="submit" value="Search" id="Search" onClick="Search();"/>
	<input type="submit" value="Clear" id="btnClear" onClick="ClearResults();"/>
</div>
<div id="divGoogleBranding"></div>
<div id="divMainContent">
	This is where your main text goes.<br />
</div>
<div id="divSearchStarting">Searching for data...</div>
<div id="divSearchResults"></div>

When you are down you should have something like this, which is the google.html example file.

<HTML>
<head>
	<title>Google AJAX Search API test</title>
	<script src="//www.google.com/jsapi?key=YOUR_API_KEY" type="text/javascript"></script>
	<script src="Util.js" type="text/javascript" />
	<script src="MyGSearch.js" type="text/javascript" />
	<script src="GoogleSearch.js" type="text/javascript" />
	<style type="text/css">
		.watermark
		{
			height:22px;
			width:150px;
			padding:2px 0 0 2px;
			border:1px solid #BEBEBE;
			background-color:#F0F8FF;
			color:gray;
			font-style: italic;
		}
		.search
		{
			height:22px;
			width:150px;
			padding:2px 0 0 2px;
			border:1px solid #BEBEBE;
			background-color:white;
			color:black;
		}
	</style>
</head>
<body>
	Google Ajax Search API Test<br />
	<div id="divSearchClose">
		<a href="javascript:ClearResults();" id="searchCloseLink">
			Close Search Results</a>
	</div>
	<div>
		<input type="text" id="txtSearchInput" />
		<input type="submit" value="Search" id="Search" onClick="Search();"/>
		<input type="submit" value="Clear" id="btnClear" onClick="ClearResults();"/>
	</div>
	<div id="divGoogleBranding"></div>
	<div id="divMainContent">
		This is where your main text goes.<br />
	</div>
	<div id="divSearchStarting">Searching for data...</div>
	<div id="divSearchResults"></div>
</body>
</HTML>

On line 3, we create a global JavaScript variable to hold a reference to the MyGSearch object. The InitializeMyGSearch function starts on line 9. Line 11 checks to see if the object already exists and is initialized, if so exits the function. Line 14 – 21 initialize the MyGSearch object and sets the basic properties of it. Lines 24 – 26, hide the search related divs. Line 28 we get a reference to the input box so that we can add our OnBlur and OnFocus events to the control. Line 34, we call the onInputBlur methods of the MyGSearch to set the watermark.

Line 38 loads all of the Google Search APIs. Line 41 calls a Google helper function to call InitializeMyGSearch once the form loads.

That’s it.

Samples

Within the ZIP file I included two HTML pages that demonstate how to use the MyGSearch object. The first sample (google.html) provides the required code for a simple search. The required Google branding div is present as well as the search results, search close, search start and main divs.

The second example (page404.html) is a page that shows what would be required to use the Google AJAX Search API to query google when a user trys to access a page that does not exist on your server. In addition, this example demonstates how you can automatically search for some text when the page loads. ou want to search.

// Add a search for the site search
searcher = new google.search.WebSearch();
// This is the label for the tab
searcher.setUserDefinedLabel("JosephGuadagno.net");
// This restricts the search to just josephguadagno.net
searcher.setSiteRestriction("josephguadagno.net");

Here you would change lines 4 and 6 to match whatever domain you want. Line 4 is the label for the tab within the results and line 6 is the domain you want to search.

Other possible modifications include adding additional Google searchers to search other domains or other file types like Images, Video or Blogs. You could also change the Google draw objects to draw the search results in a result set.

References

Get your Google API Key: //code.google.com/apis/ajaxsearch/signup.html
Google AJAX API: //code.google.com/apis/ajaxsearch/
Google AJAX API Documentation: //code.google.com/apis/ajaxsearch/documentation/
Google AJAX API User Group: //groups-beta.google.com/group/Google-AJAX-Search-API

%d bloggers like this: