|
Edelman Technologies
http://blog.edelmantech.com/content/2007/03/promote_google_cses_with_open_search_javascript_and_cookies.php
View Full Version
Promote Google CSEs with Open Search, Javascript, and Cookies
By David Edelman on 03.23.07
Filed Under: Search
For the past few months, I've been falling in love with Google Custom Search Engines. So far I've built two sites, both of which have seen steadily growing traffic. Diabetes Web Search indexes 250 of the most relevant diabetes organizations, government sites, forums and blogs. Search and Cure Diabetes uses the entire Google index but donates all ad profits to diabetes-related organizations.
Create an Open Search Plugin
One of the keys to promoting a custom search engine is letting users easily add it to their browser in Firefox 2 and Internet Explorer 7. To do this, you first need to create a simple XML file that tells the browser about your search engine. Here's the one I'm using for SearchAndCure.com. It's called opensearch.xml and I placed it in my root directory.
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
xmlns:moz="http://www.mozilla.org/2006/browser/search/">
<ShortName>Search and Cure Diabetes</ShortName>
<Description>All profits from this search engine support diabetes cure research.</Description>
<InputEncoding>UTF-8</InputEncoding>
<Image width="16" height="16">data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8%2F9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAAKTWlDQ1BQaG90b3Nob3AgSUNDIHByb2ZpbGUAAHjanVN3WJP3Fj7f92UPVkLY8LGXbIEAIiOsCMgQWaIQkgBhhBASQMWFiApWFBURnEhVxILVCkidiOKgKLhnQYqIWotVXDjuH9yntX167%2B3t%2B9f7vOec5%2FzOec8PgBESJpHmomoAOVKFPDrYH49PSMTJvYACFUjgBCAQ5svCZwXFAADwA3l4fnSwP%2FwBr28AAgBw1S4kEsfh%2F4O6UCZXACCRAOAiEucLAZBSAMguVMgUAMgYALBTs2QKAJQAAGx5fEIiAKoNAOz0ST4FANipk9wXANiiHKkIAI0BAJkoRyQCQLsAYFWBUiwCwMIAoKxAIi4EwK4BgFm2MkcCgL0FAHaOWJAPQGAAgJlCLMwAIDgCAEMeE80DIEwDoDDSv%2BCpX3CFuEgBAMDLlc2XS9IzFLiV0Bp38vDg4iHiwmyxQmEXKRBmCeQinJebIxNI5wNMzgwAABr50cH%2BOD%2BQ5%2Bbk4eZm52zv9MWi%2FmvwbyI%2BIfHf%2FryMAgQAEE7P79pf5eXWA3DHAbB1v2upWwDaVgBo3%2FldM9sJoFoK0Hr5i3k4%2FEAenqFQyDwdHAoLC%2B0lYqG9MOOLPv8z4W%2Fgi372%2FEAe%2Ftt68ABxmkCZrcCjg%2F1xYW52rlKO58sEQjFu9%2Bcj%2FseFf%2F2OKdHiNLFcLBWK8ViJuFAiTcd5uVKRRCHJleIS6X8y8R%2BW%2FQmTdw0ArIZPwE62B7XLbMB%2B7gECiw5Y0nYAQH7zLYwaC5EAEGc0Mnn3AACTv%2FmPQCsBAM2XpOMAALzoGFyolBdMxggAAESggSqwQQcMwRSswA6cwR28wBcCYQZEQAwkwDwQQgbkgBwKoRiWQRlUwDrYBLWwAxqgEZrhELTBMTgN5%2BASXIHrcBcGYBiewhi8hgkEQcgIE2EhOogRYo7YIs4IF5mOBCJhSDSSgKQg6YgUUSLFyHKkAqlCapFdSCPyLXIUOY1cQPqQ28ggMor8irxHMZSBslED1AJ1QLmoHxqKxqBz0XQ0D12AlqJr0Rq0Hj2AtqKn0UvodXQAfYqOY4DRMQ5mjNlhXIyHRWCJWBomxxZj5Vg1Vo81Yx1YN3YVG8CeYe8IJAKLgBPsCF6EEMJsgpCQR1hMWEOoJewjtBK6CFcJg4Qxwicik6hPtCV6EvnEeGI6sZBYRqwm7iEeIZ4lXicOE1%2BTSCQOyZLkTgohJZAySQtJa0jbSC2kU6Q%2B0hBpnEwm65Btyd7kCLKArCCXkbeQD5BPkvvJw%2BS3FDrFiOJMCaIkUqSUEko1ZT%2FlBKWfMkKZoKpRzame1AiqiDqfWkltoHZQL1OHqRM0dZolzZsWQ8ukLaPV0JppZ2n3aC%2FpdLoJ3YMeRZfQl9Jr6Afp5%2BmD9HcMDYYNg8dIYigZaxl7GacYtxkvmUymBdOXmchUMNcyG5lnmA%2BYb1VYKvYqfBWRyhKVOpVWlX6V56pUVXNVP9V5qgtUq1UPq15WfaZGVbNQ46kJ1Bar1akdVbupNq7OUndSj1DPUV%2Bjvl%2F9gvpjDbKGhUaghkijVGO3xhmNIRbGMmXxWELWclYD6yxrmE1iW7L57Ex2Bfsbdi97TFNDc6pmrGaRZp3mcc0BDsax4PA52ZxKziHODc57LQMtPy2x1mqtZq1%2BrTfaetq%2B2mLtcu0W7eva73VwnUCdLJ31Om0693UJuja6UbqFutt1z%2Bo%2B02PreekJ9cr1Dund0Uf1bfSj9Rfq79bv0R83MDQINpAZbDE4Y%2FDMkGPoa5hpuNHwhOGoEctoupHEaKPRSaMnuCbuh2fjNXgXPmasbxxirDTeZdxrPGFiaTLbpMSkxeS%2BKc2Ua5pmutG003TMzMgs3KzYrMnsjjnVnGueYb7ZvNv8jYWlRZzFSos2i8eW2pZ8ywWWTZb3rJhWPlZ5VvVW16xJ1lzrLOtt1ldsUBtXmwybOpvLtqitm63Edptt3xTiFI8p0in1U27aMez87ArsmuwG7Tn2YfYl9m32zx3MHBId1jt0O3xydHXMdmxwvOuk4TTDqcSpw%2BlXZxtnoXOd8zUXpkuQyxKXdpcXU22niqdun3rLleUa7rrStdP1o5u7m9yt2W3U3cw9xX2r%2B00umxvJXcM970H08PdY4nHM452nm6fC85DnL152Xlle%2B70eT7OcJp7WMG3I28Rb4L3Le2A6Pj1l%2Bs7pAz7GPgKfep%2BHvqa%2BIt89viN%2B1n6Zfgf8nvs7%2Bsv9j%2Fi%2F4XnyFvFOBWABwQHlAb2BGoGzA2sDHwSZBKUHNQWNBbsGLww%2BFUIMCQ1ZH3KTb8AX8hv5YzPcZyya0RXKCJ0VWhv6MMwmTB7WEY6GzwjfEH5vpvlM6cy2CIjgR2yIuB9pGZkX%2BX0UKSoyqi7qUbRTdHF09yzWrORZ%2B2e9jvGPqYy5O9tqtnJ2Z6xqbFJsY%2BybuIC4qriBeIf4RfGXEnQTJAntieTE2MQ9ieNzAudsmjOc5JpUlnRjruXcorkX5unOy553PFk1WZB8OIWYEpeyP%2BWDIEJQLxhP5aduTR0T8oSbhU9FvqKNolGxt7hKPJLmnVaV9jjdO31D%2BmiGT0Z1xjMJT1IreZEZkrkj801WRNberM%2FZcdktOZSclJyjUg1plrQr1zC3KLdPZisrkw3keeZtyhuTh8r35CP5c%2FPbFWyFTNGjtFKuUA4WTC%2BoK3hbGFt4uEi9SFrUM99m%2Fur5IwuCFny9kLBQuLCz2Lh4WfHgIr9FuxYji1MXdy4xXVK6ZHhp8NJ9y2jLspb9UOJYUlXyannc8o5Sg9KlpUMrglc0lamUycturvRauWMVYZVkVe9ql9VbVn8qF5VfrHCsqK74sEa45uJXTl%2FVfPV5bdra3kq3yu3rSOuk626s91m%2Fr0q9akHV0IbwDa0b8Y3lG19tSt50oXpq9Y7NtM3KzQM1YTXtW8y2rNvyoTaj9nqdf13LVv2tq7e%2B2Sba1r%2Fdd3vzDoMdFTve75TsvLUreFdrvUV99W7S7oLdjxpiG7q%2F5n7duEd3T8Wej3ulewf2Re%2FranRvbNyvv7%2ByCW1SNo0eSDpw5ZuAb9qb7Zp3tXBaKg7CQeXBJ9%2BmfHvjUOihzsPcw83fmX%2B39QjrSHkr0jq%2Fdawto22gPaG97%2BiMo50dXh1Hvrf%2Ffu8x42N1xzWPV56gnSg98fnkgpPjp2Snnp1OPz3Umdx590z8mWtdUV29Z0PPnj8XdO5Mt1%2F3yfPe549d8Lxw9CL3Ytslt0utPa49R35w%2FeFIr1tv62X3y%2B1XPK509E3rO9Hv03%2F6asDVc9f41y5dn3m978bsG7duJt0cuCW69fh29u0XdwruTNxdeo94r%2Fy%2B2v3qB%2FoP6n%2B0%2FrFlwG3g%2BGDAYM%2FDWQ%2FvDgmHnv6U%2F9OH4dJHzEfVI0YjjY%2BdHx8bDRq98mTOk%2BGnsqcTz8p%2BVv9563Or59%2F94vtLz1j82PAL%2BYvPv655qfNy76uprzrHI8cfvM55PfGm%2FK3O233vuO%2B638e9H5ko%2FED%2BUPPR%2BmPHp9BP9z7nfP78L%2FeE8%2Fsl0p8zAAAABGdBTUEAALGOfPtRkwAAACBjSFJNAAB6JQAAgIMAAPn%2FAACA6QAAdTAAAOpgAAA6mAAAF2%2BSX8VGAAABP0lEQVR42mJkYJj5nwEPEBRkZ2BnZ2ZYUHbF2r2w4xi6PCMhA5CBje6bTd62H2dWTO3cRpYBMMDKysTw61cKI1YD7A2%2FMqjJ%2F2P4%2B4%2BRgYGBgYGZ6T%2FD3ceMDE9eMDDcesoDV9eQ%2BmhP%2FawWVwwDtvW%2FYLBVOIth662P2gzGCQpwvrrs52%2BHZu%2BRZcJ03j%2Bszlbjv8qwo%2B8eg6AgOwMDAwPDzce8XImT8t9iGPD7NxNOv1srXkfhb9v2iIGJgQLAxcVCmQEMDAyUGfDt2x8GogORgYGB4eh9TQwxFmID8dZHbQaPIgUGBoafcLHP67eyYBjQuYiXYb28HUZCOn9PGEVzW%2BpjdZ6AjX9JTsqCguwMQeZ3F8zZ3pSI1Qv4NDIwMDAc6drFrZWy9BvOMMClcW%2F7IWnD9LnPGBjiUeQBAwCRHmfgzVAdxAAAAABJRU5ErkJggg%3D%3D</Image>
<Url type="text/html" method="GET" template="http://www.searchandcure.com/?cx=009495457297745205407%3Apgbfdwvnygi&q={searchTerms}&sa=Search&cof=FORID%3A9">
</Url>
<moz:SearchForm>searchFormURL</moz:SearchForm>
</OpenSearchDescription>
The OpenSearchDescription, ShortName, Description, and InputEncoding should be fairly straightforward. The Image section includes the actual data for the PNG icon that I want associated with the search engine. To get this information, upload it to the data: URI kitchen with the base64 box checked. The Url type tells the browser how to format the search engine query and what page to direct it to. For a more detailed look at creating your own Open Search xml file, check out the Mozilla developer network.
Once you've created your Open Search plugin, you'll need to tell the user about it. To do this, reference it in the section of your HTML file. This is done with one simple line:
<link rel="search" type="application/opensearchdescription+xml" title="searchTitle" href="pluginURL">
So far, so good. We've created an Open Search plugin and told the browser how to access it. When a user visits your site using FF2 or IE7, your engine will now appear in the search engine drop-down box in the browser toolbar
Include an "Add My Search Engine" Feature
Below is a great piece javascript code by Patrick Hunlock that distinguishes between the users browser and prompts them to add your search engine. I've modified it so that it sets a cookie when the user adds the search engine to the the browser toolbar. This way I can use a conditional and only display the "Add Search Engine to Browser" link if the user has not yet added it.
In order for this to work in Firefox, you'll need to follow Hunlock's instructions (see link above) and create a .src file for your search engine. The Firefox way is actually better because when the user adds your engine by using the script below, the browser will regularly check the .src file for updates. If the user adds it from the browser drop-down or in IE7, they must delete and re-add the search engine in order for any changes you make to take effect (e.g. changing the icon or the query parameters).
<script type="text/javascript">
function addEngine()
{
if ((typeof window.sidebar == "object") && (typeof window.sidebar.addSearchEngine == "function"))
{
window.sidebar.addSearchEngine(
"http://www.searchandcure.com/searchandcure.src",
"http://www.searchandcure.com/searchandcure.png",
"Search and Cure Diabetes!",
"Cure" );
setCookie("addedengine","true",3650);
} else {
if (window.external.AddSearchProvider) {
window.external.AddSearchProvider('http:
setCookie("addedengine","true",3650);
}
}
}
</script>
Here's the simple setCookie script I used. You can use a more advanced one or your own if your prefer or not set a cookie at all.
<script type="text/javascript">
function setCookie(name, value, days)
{
if (days) {
var date = new Date();
date.setTime(date.getTime()+(days*24*60*60*1000));
var expires = "; expires="+date.toGMTString();
}
else var expires = "";
document.cookie = name+"="+value+expires+"; path=/";
}
function readCookie(name)
{
var ca = document.cookie.split(';');
var nameEQ = name + "=";
for(var i=0; i < ca.length; i++) {
var c = ca[i];
while (c.charAt(0)==' ') c = c.substring(1, c.length);
if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length, c.length);
}
return null;
}
function eraseCookie(name)
{
createCookie(name, "", -1);
}
</script>
Now you're almost done. If you'd like, you can simply put an onClick="addEngine()" event in a link your page and call it a day. I chose to go one step further and use a browser detection script and cookie check to make sure I only show this to those whose browser supports Open Search and have not yet added the search engine. This will only work on a .php web page.
<?php
$browser = browser_detection('full');
$addedengine = $_COOKIE['addedengine'];
if ($addedengine != "true" && (($browser[0] == 'moz' && $browser[1] >= '1.8') || ($browser[0] == 'ie' && $browser[1] >= '8')))
{
?>
<div id="addengine"><a href="" onClick="addEngine();">Add this search engine to your web browser!</a></div>
<?php
}
?>
Thats it! You now have an easy way to promote your custom search engine to your visitors. If you'd like a more in depth explanation of any section, please ask in the comments.
|