devot:eeDevoted to ExpressionEngine

Display search results from your Google Custom Search Engine using standard EE template tags via the Google Custom Search JSON/Atom API.

Who’s it for?

This module is a great search solution for your site if:

• you have a low-to-medium traffic site;
• you want better relevance when searching, including the ability to add synonyms for search terms and more;
• you need to include the contents of PDF files in your search results;
• you need to search non-EE content (e.g., static HTML files) or content from other domains or sites, in addition to your EE content;

The Google Custom Search API currently limits searches to 100 results per query, and 100 free queries per day. There is no daily query limit if you enable billing on your account (additional queries are $5 per 1000 queries, per day.)

Requirements

 
• A Google Custom Search Engine ID or Linked Custom Search Engine file
 
• A Google Custom Search API key
 
• cURL and OpenSSL support on your server

Template Tags

{exp:google_custom_search:form}

This tag pair outputs the search form you’ll use to perform your custom search. It accepts three tag parameters:

• results_page="template_group/template" – (required) the template path where your search results code is located
 
• id="form_id" – the "id" attribute for your form
 
• class="form_class" – the "class" attribute for your form
 
• honeypot="yes" – whether or not to add a hidden “honeypot” field to the form, useful if you’re experiencing search spam. Defaults to “no”.

Example:

{exp:google_custom_search:form results_page="search/results" id="search_form" class="form"}
<div>
    <input type="text" name="keywords" size="20" placeholder="Enter keywords" />
    <input type="submit" name="submit" value="Search" />
</div>
{/exp:google_custom_search:form}

{exp:google_custom_search:results}

This tag pair outputs your CSE search results. It accepts eight parameters:

 
• api_key="your_api_key" – (required) your Google Custom Search API key
 
• cse="your_cse_id" – (required if no cref) your Google Custom Search Engine unique ID
 
• cref="http://yourdomain.com/cse.xml" – (required if no cse) URL to an XML-formatted Custom Search Engine file
 
• keywords="{segment_3}" – (required) the URL segment which holds your encoded keywords. It will be the segment which follows the current template segment.
 
• limit="10" – the number of results to return per-page. Valid values are any number between 1 and 10 (default).
 
• safe="off" – search safety level. Valid values are "high", "medium", or "off" (default).
 
• filter="on" – duplicate content filter. Valid values are "off" or "on" (default).
 
• language="lang_en" – restrict the search to documents written in a particular language. See accepted values.
 
• replace_title="string of text" – a common string of text in your page titles that you’d like removed from titles in your results (e.g. your site name).

The following single variables are available within the {exp:google_custom_search:results} tag, both as variables and conditionals:

 
• {search_results} – will be TRUE if your search returned results
 
• {no_search_results} – will be TRUE if your search returned no results
 
• {keywords} – your search phrase
 
• {total_search_results} – total results for your search via the API (maximum 100)
 
• {total_google_search_results} – total results for your search via the Google (no maximum)
 
• {results_overflow} – will be TRUE if there were more Google search results than the API could return
 
• {google_results_url} – URL to continue your search via a Google-hosted results page
 
• {last_results_page} – will be TRUE if you are on the last page of results
 
• {pagination} – will be TRUE if there are more pages of results in either direction
 
• {next_page} – link to the next page of results
 
• {previous_page} – link to the previous page of results
 
• {current_page} – page number of the current page of search results
 
• {total_pages} – total number of pages of search results available via the API
 
• {current_results_start} – starting index of the current search results, based on the current page
 
• {current_results_end} – end index of the current search results, based on the current page

Your search results are displayed within the {results} tag pair. Within this tag pair, you have access to the following variables:

 
• {title} – the page title of the search result
 
• {title_formatted} – the page title of the search result, with Google’s search phrase emphasis intact
 
• {excerpt} – the relevant content snippet of the search result
 
• {excerpt_formatted} – the relevant content snippet of the search result, with Google’s search phrase emphasis intact
 
• {url} – the URL to the search result
 
• {format} – the file format of the search result, based on the result’s file extension
 
• {result_count} – the index of the current search result within the current page of results
 
• {total_page_results} – the total number of results returned for the current page

Example:

{exp:google_custom_search:results cse="015444475426479558420948:us-4opsqdy" api_key="BtzaWyGig7fwERFHHY-J7A8Q-DFP5eWzGryGtpA" keywords="{segment_3}" replace_title=" | My Great Site"}
{if no_search_results}<p>Sorry, your search returned no results.</p>{/if}
{if search_results}
    <p>Your search for <strong>{keywords}</strong> received {total_search_results} results.</p>
    {results}
        {if result_count == "1"}<ol>{/if}
        <li><a href="{url}" class="result_{format}">{title}</a> -  {excerpt} <small>({url})</small></li>
        {if result_count == total_page_results}</ol>{/if}
    {/results}
    {if pagination}
        <div class="pagination">
            <p>Page {current_page} of {total_pages} (showing results {current_results_start} - {current_results_end} of {total_search_results})</p>
            {if next_page}<p><a href="{next_page}">Next Page</a></p>{/if}
            {if previous_page}<p><a href="{previous_page}">Previous Page</a></p>{/if}
        </div>
    {/if}
    {if last_results_page && results_overflow}
        <p><a href="{google_results_url}" target="_blank">View all {total_google_search_results} results on Google</a></p>
    {/if}
{/if}
{/exp:google_custom_search:results}

{exp:google_custom_search:keywords}

This single tag outputs the current search keywords. It accepts one required parameter:

• keywords="{segment_3}" – (required) the segment which contains the md5 hash of your search terms.

Example:

{exp:google_custom_search:keywords keywords="{segment_3"}

Change Log

• 1.0.9 - Fix for PHP errors when returned results have no titles or summaries
• 1.0.8 - Added new (optional) “honeypot” parameter to the search form to trap search spam
• 1.0.7 - Added new variables: {current_page}, {total_pages}, {current_results_start}, and {current_results_end}
• 1.0.6 - Added more useful error messages when the API call fails
• 1.0.5 (the Marcus Neto edition) - Fixed issues with servers running PHP < 5.2 where the supplemental JSON library was not loading; added some template debugger messages
• 1.0.4 - Fixed potential issue with loading control panel view files
• 1.0.3 - Changed default results language from English to any language
• 1.0.2 - Now using md5 hashes for keyword segments instead of base64 encoding due to potential issues with equals (=) characters in the URL
• 1.0.1 - Added {format} variable, removed {is_pdf} variable
• 1.0 - Initial release

Support

Questions or issues? Please post on the officially-supported devot:ee forums.

This entry was last updated February 7, 2012, 10:13 am.

Disclaimer: Information about ExpressionEngine add-ons is provided as a service to you, the user, and every member of the ExpressionEngine community. Devot:ee is not responsible if you hose, mangle, wreck, or otherwise destroy your EE website by installing an add-on that you found out about at this site, regardless of its rating, Favorites status, commercial or free status, or general popularity. Caveat EEmptor!