Google Web Search API (Deprecated)
2011-07-11 21:27
639 查看
Class Reference
Note: The Google Web Search API has been officially deprecated as of November 1, 2010. It will continue to work as per our deprecation policy, but the number of requests you may make per day will be limited. Therefore, we encourage you to move to the new Custom Search API.The Google Search API is a JavaScript API implemented in the following classes.We've updated this documentation to make use of the API loader. This loader makes it easier to use multiple Google APIs on the same page and unifies the namespaces across them. If you don't want to change your code, that's fine -- it won't break and the old namespace will continue to work. We hope you'll choose to transition to the new loader and namespace, as we'll continue to extend it for future APIs.
Check to show old class name and namespace scheme (e.g. GwebSearch,etc.)
Table of Contents
The Search Control GSearchControlgoogle.search.SearchControl GSearchForm google.search.SearchForm google.search.CustomSearchControl Searchers GSearchgoogle.search.Search GwebSearchgoogle.search.WebSearch Searcher and Drawing Options GsearcherOptions google.search.SearchOptions GdrawOptions google.search.DrawOptions Result Objects GwebResult Result Styling GwebResult CSS Structure Flash and other Non-Javascript Environments Web Search Specific ArgumentsNew Args!The Search Control
GSearchControlgoogle.search.SearchControl
An instance ofGSearchControlgoogle.search.SearchControlrepresents a single search control on a page. Each search control manages the presentation of the user interface object and the search mechanism for a selected set of searcher objects (objects which implement the
GSearch google.search.Searchinterface).
GSearchControlgoogle.search.SearchControl - Constructor
Constructor | Description |
---|---|
GSearchControl()google.search.SearchControl() | Creates a new search control object. The search control object is a container for searchers, objects which implement the GSearchgoogle.search.Searchinterface. The search control object is not operational until is has at least one searcher child. A search control is bound to an html container using the .draw()method. Note that searcher objects may not be added to a search control once its draw()method has been called. The expected order of operations is: sc = new GSearchControl()google.search.SearchControl(); sc.addSearcher(); sc.draw(); Once these steps have occurred, the search control is active and ready to begin performing searches. |
GSearchControlgoogle.search.SearchControl - Methods
Method | Description |
---|---|
.addSearcher(searcher, opt_options?) | This method adds a searcher object to the search control. Once added, the search control will coordinate the activities of the searcher. It will coordinate the execution of searches, handle the related search completion events, provide a location where results are to be rendered, and provide a ui for "keeping" or "clipping" search results. The method accepts an optional GsearcherOptionsgoogle.search.SearchOptionsobject which is used to specify various searcher specific options: searcher - supplies a searcher object opt_options - if specified, supplies configuration options for this searcher returns - n/a |
.draw(element, opt_drawOptions?) | This method is the final step needed to activate a search control object. It may only be called once all searchers have been added into the search control. When called, this method produces the user interface and search result containers for each configured searcher, and then sets up the various linkages needed to coordinate parallel searches across all of the searchers. The method requires that the caller supply an html block element, typically a divelement which the control draws within. The control operates best when provided with at least 300px of width and will scale reasonably well down to ~250px. The default user interface style is a linear style where the control inputs are at the top followed by a linear set of stacked results. Optionally, callers may request a tabbed user interface which works well when vertical real estate is at a premium. element - supplies an html block element that acts as a container for the control opt_drawOptions - if specified, supplies a GdrawOptionsgoogle.search.DrawOptionsobject which can be used to specify linear or tabbed drawing mode. The object can also be used to supply the search control with a text input element that should be used to capture query terms. If unspecified, a linear drawing mode is assumed and the control allocates and manages its own text input element. returns - n/a |
.setTimeoutInterval(timeoutInterval) | When an application is providing its own input control and asking the search control to use that, the search control uses an input timer to determine when to execute a search. Each time a user types into the search controls text input area, a countdown timer is initialized. When the timer executes, a search is requested. The time lag between the last keystroke and the initiation of a search is programmed using this API. Note: The default value of the control is GSearchControlgoogle.search.SearchControl.TIMEOUT_MEDIUM(about 500ms). timeoutInterval - supplies the value for the timeoutInterval, the amount of time between the last keystroke and the execution of a resulting search. Valid values include: GSearchControlgoogle.search.SearchControl.TIMEOUT_SHORT- used to specify a very short delay ~350ms. GSearchControlgoogle.search.SearchControl.TIMEOUT_MEDIUM- used to specify a medium delay of ~500ms. GSearchControlgoogle.search.SearchControl.TIMEOUT_LONG- used to specify a long delay ~700ms. returns - n/a |
.execute(opt_query?) | This method causes the search control to initiate a sequence of parallel searches across all of the searchers configured into the control. If the opt_queryargument is supplied, its value is placed within the search controls input text box, and becomes the search expression for the parallel search. Otherwise, the current value of the search control input text box is used. Note: this method allows applications to automate portions of the search control. For example, an application could choose to automatically initiate a search whenever the user hovers over a word or phrase or makes some other application specific gesture. As a side effect of this call, the current set of search results displayed, as well as the search results stored within each of the controlled searcher objects is cleared. opt_query - supplies an optional search expression used by the ensuing search. If not specified, then the search expression present in the search control's text input box is used. returns - n/a |
.setOnKeepCallback(object, method, opt_keepLabel?) | This method is used to inform the search control that the caller would like to be notified when a user has selected for copy, one of the search results managed by the control. If this method is not called, then the user is not offered an opportunity to copy search results. If the method is called, each search result is annotated with a text link, underneath the search result. Clicking on this link will cause the specified method to be called on the specified object, passing in a GResultgoogle.search.Resultobject associated with the search result. This method allows the caller to specify a built-in, system defined text label value which invites the user to copy a result, or to specify a label more meaningful to the calling application. When using the system defined labels, the value is automatically translated in the language that the rest of the control is running in. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. For instance, if this method is called as .setOnKeepCallback(foo, MyObject.prototype.myKeephandler), when a user clicks on the keep label, a call to foo.myKeephandler()is called. opt_keepLabel - supplies an optional text label that sits beneath each search result which, when clicked, triggers a callback into the specified object/method. Valid values include: GSearchControlgoogle.search.SearchControl.KEEP_LABEL_SAVE- a label value of "save" GSearchControlgoogle.search.SearchControl.KEEP_LABEL_KEEP- a label value of "keep" GSearchControlgoogle.search.SearchControl.KEEP_LABEL_INCLUDE- a label value of "include" GSearchControlgoogle.search.SearchControl.KEEP_LABEL_COPY- a label value of "copy" (default) GSearchControlgoogle.search.SearchControl.KEEP_LABEL_BLANK- a blank label value is used, this works well when all you want is the copy graphic (selectable via css) Any other value - the value passed becomes the label. The caller is responsible for localization. returns - n/a |
.setResultSetSize(switchTo) | This method is called to select the number of results returned by each of the searchers. This can be a scalar from 1 to 8 (inclusive), or it can be an enumeration. From the sample applications, you have probably seen the more/less twiddle control at the top of the search control. This method is used by that twiddle control. switchTo - supplies a scalar value between 1 and 8 or an enumeration which indicates the desired number of search results to return for each configured searcher. Valid values include: A scalar between 1 and 8 GSearchgoogle.search.Search.LARGE_RESULTSET- request a large number of results (typically 8 results) GSearchgoogle.search.Search.SMALL_RESULTSET- request a small number of results (typically 4 results) google.search.Search.FILTERED_CSE_RESULTSET- request up to 10 results. This will only work for Web Search queries scoped to a Filter Custom Search engine, otherwise an error will be returned. returns - n/a |
.cancelSearch() | This method is used to tell the search control to ignore all incoming search result completions. The internal state used by this method is reset, to allow searches each time a new search is requested. The intended use of this method is to help applications cope with ui flashing that can occur as slow input triggers inadvertent searches. By using this method each time input is sensed, previous searches based on partial input can easily be ignored. returns - n/a |
.clearAllResults() | This method is used to clear all of the search results out of the search control. returns - n/a |
.setLinkTarget(linkTarget) | This method is called to set the link target used for links embedded in search results. The default value is GSearchgoogle.search.Search.LINK_TARGET_BLANKwhich specifies that links will open in a new browser window. When this method is called, a search control wide link target setting is established. This effects all searchers that are currently attached to the search control as well as all searchers that are subsequently added to the control. linkTarget - supplies the target frame that links should open within, valid values include: GSearchgoogle.search.Search.LINK_TARGET_BLANK- links will open in a new window, e.g., <A href=... target=_blank ...> GSearchgoogle.search.Search.LINK_TARGET_SELF- links will open in the same window and frame, e.g., <A href=... target=_self ...> GSearchgoogle.search.Search.LINK_TARGET_TOP- links will open in the topmost frame, e.g., <A href=... target=_top ...> GSearchgoogle.search.Search.LINK_TARGET_PARENT- links will open in either the topmost frame, or replace the current frame, e.g., <A href=... target=_parent ...> anything-else - links will open in the specified frame or window, e.g., <A href=... target=anything-else ...> returns - n/a |
.setSearchCompleteCallback(object, method) | This method is used to inform the search control that the caller would like to be notified when a search completes. Note, the granularity of this call is the searcher level, NOT the search control level. What this means is that if your search control contains 5 searchers and you execute a search, as each searcher completes, your callback will be called. Note also, that not all searches will result in completion so be careful not to code deadlocks where you assume that a single completion will occur for each search. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. For instance, if this method is called as .setSearchCompleteCallback(foo, MyObject.prototype.mySearchComplete), when a search completes, a call to foo.mySearchComplete(searchControl, searcher)is called. The first argument of the callback, searchControlsupplies the search control, and the second argument searchersupplies the searcher object that just completed a search. returns - n/a |
.setSearchStartingCallback(object, method) | This method is used to inform the search control that the caller would like to be notified right before a search begins. Note, the granularity of this call is the searcher level, NOT the search control level. What this means is that if your search control contains 5 searchers and you execute a search, as each searcher is told to begin searching, your method will be called. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. For instance, if this method is called as .setSearchStartingCallback(foo, MyObject.prototype.mySearchStarting), when a search begins, a call to foo.mySearchStarting(searchControl, searcher, query)is called. The first argument of the callback, searchControlsupplies the search control, the second argument searchersupplies the searcher that is about to start a search, and the third argument querysupplies the query. returns - n/a |
.setNoResultsString(str) | Normally, when a search produces no results, the search control slot for the searcher is left empty. This method allows the caller to specify a string that supplies a default "result". The system contains a value of GSearchControlgoogle.search.SearchControl.NO_RESULTS_DEFAULT_STRINGwhich you can use. This is a localized string that means "No Results" in all supported locales. str - supplies a string value that is used when a search yields no results.. returns - n/a |
GSearchControlgoogle.search.SearchControl - Static methods
Static method | Description |
---|---|
.inlineCurrentStyle(node, opt_deep?) | This utility function is used to clone the current computed style for the specified html node (or tree if opt_deep is specified) and inline the current style into the node. In some instances this function is useful, mainly in conjunction with an on keep handler where the application wishes to preserve a set of html styles while passing a piece of html from one application to another, where the receiving application does not have the associated style sheet. The simplest example of this scenario is in the case of an email application where the email application is using the Google Search API to allow users to clip search results into a message composition window where they will be emailed as html to another user. The recipient's email application in some cases will have no knowledge of Google Search API and will therefore not normally carry its style sheet. To account for this, we provide this method so the originating email application can inline the current styles so that the recipient can read the message with full fidelity. node - supplies and html node whose style should be inlined opt_deep - if specified, the inline operation is recursive inlining the styles for the current node and its descendants. returns - n/a Note: this method is not currently implemented on the Safari web browser. |
GSearchControl google.search.SearchControl - Public Properties
This object does not expose any public properties.GSearchFormgoogle.search.SearchForm
Applications that use the GSearchgoogle.search.Search objects in standalone form, rather than under control of theGSearchControlgoogle.search.SearchControlwill often have a need to capture and process user-generated search requests. The
GSearchFormgoogle.search.SearchForm()object is a light weight object that is designed for exactly this use case. It provides applications with a text input element, a search button, an optional clear button, as well as all standard branding.
GSearchFormgoogle.search.SearchForm - Constructor
Constructor | Description |
---|---|
GSearchFormgoogle.search.SearchForm(enableClear, element) | Creates a new search form object. The search form object supplies user interface elements, methods, properties, and callbacks designed to allow applications to control a collection of GSearchgoogle.search.Search()objects. The user interface and capabilities match whats available to applications using the GSearchControlgoogle.search.SearchControl())(in fact, the GSearchControlgoogle.search.SearchControl()is internally based on this object. The expected order of operations is: sf = new GSearchFormgoogle.search.SearchForm(true/false, container); sf.setOnSubmitCallback(object, method); optional - sf.setOnClearCallback(object, method); Once these steps have occurred, the search form is active and ready to begin receiving and processing user input. The method accepts a required enableClearargument as well as a required elementargument enableClear - when true, the search form should contain a clear button, otherwise, no clear button is created element - supplies the HTML node that should act as a container for this form |
GSearchFormgoogle.search.SearchForm - Methods
Method | Description |
---|---|
.setOnSubmitCallback(object, method) | This method registers an object/method combination that is called when the search form is "submitted". This event occurs when the user clicks on the search button, or when the user hits enter while focused on the text input element. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form. A typical method might look like this: App.prototype.onSubmit = function(form) { if (form.input.value) { this.localSearcher.execute(form.input.value); } return false; }Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the submit event. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. The method is passed a reference to this form and must return false. |
.setOnClearCallback(object, method) | This method registers an object/method combination that is called when the clear button in the search form is pressed. It is an error to call this method if the search form was created without a clear button. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form. A typical method might look like this: App.prototype.onClear = function(form) { this.myClearFunction(); return false; }Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the clear event. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. The method is passed a reference to this form and must return false. |
.execute(opt_string?) | This method allows an application to "submit" the form. This involves optionally setting the form's text input element and then calling the registered on-submit callback method established using .setOnSubmitCallback(). opt_string - if present, supplies a string value that is placed in the form's text input element prior to invoking the on-submit callback method. returns - n/a |
GSearchFormgoogle.search.SearchForm - Static methods
This object does not expose any static methods.GSearchFormgoogle.search.SearchForm - Public Properties
The following collection of public properties are exposed by the google.search.SearchForm.Property | Description |
---|---|
.input | This property is the text input element for the form. Applications are free to read and write this property at will. Typical use is that in an on-submit callback handler, an application will read form.input.valueand then process this string, typically by calling .execute()on a searcher under its control. |
.userDefinedCell | The search form's internal structure is a pair of HTML tables. The upper table contains the text input element, the localized search button, and an optional clear button. The lower table contains an application specific free cell, the left hand cell in the table, as well as a right aligned set of Google branding, including both text and an image. This property, the .userDefinedCellproperty is the DOM node of the table cell designed to hold application specific content. An application is free to use this space to deposit information in close proximity to the search form and aligned with the standard Google branding. |
Searchers
GSearchgoogle.search.Search
An instance of theGSearchgoogle.search.Searchclass provides the ability to execute searches and receive results from a specific search service. This object is not directly used; it is a base class which service-specific searchers inherit from. The methods and properties described below apply to all objects that inherit from this base class. Each of those objects may supply additional interfaces as well.
The expected usage of this object is in conjunction with the
GSearchControlgoogle.search.SearchControlwhere the search control provides both user interface and coordination. That said, it is perfectly acceptable for you to use this object independently, but just make sure you are not attempting to share the same instance of a searcher object between your application logic and a search control object.
GSearchgoogle.search.Search - Constructor
Constructor | Description |
---|---|
GSearchgoogle.search.Search() | Creates a new searcher object. Note: Since this is a base class, it is unlikely that applications will make direct use of this constructor and instead will use the constructor as a side effect of creating a service specific searcher object (e.g., GwebSearchgoogle.search.WebSearch). |
GSearchgoogle.search.Search - Methods
Method | Description |
---|---|
.setResultSetSize(indicator) | This method is called to select the number of results returned by each of the searchers. This can be a scalar from 1 to 8 (inclusive), or it can be an enumeration. switchTo - supplies a scalar value between 1 and 8 or an enumeration which indicates the desired number of search results to return for each configured searcher. Valid values include: A scalar between 1 and 8 GSearchgoogle.search.Search.LARGE_RESULTSET- request a large number of results (typically 8 results) GSearchgoogle.search.Search.SMALL_RESULTSET- request a small number of results (typically 4 results) google.search.Search.FILTERED_CSE_RESULTSET- request up to 10 results. This will only work for Web Search queries scoped to a Filter Custom Search engine, otherwise an error will be returned. returns - n/a |
.getResultSetSize() | This method returns the current result set size, the value established by the previous method. Returns an enumeration or scalar which indicates the current number of search results to return. Valid values include: A scalar between 1 and 8 GSearchgoogle.search.Search.LARGE_RESULTSET- large number of results (typically 8 results) GSearchgoogle.search.Search.SMALL_RESULTSET- small number of results (typically 4 results) google.search.Search.FILTERED_CSE_RESULTSET- up to 10 results (only available for Filtered Custom Search engines) |
.clearResults() | Upon successful completion of a search, the searcher object holds on to a collection of search results which describe the outcome of a particular search. This method is used to reset the searcher, clearing out all results. This method is implicitly called prior to the execution of a new search. returns - n/a |
.execute(query) | This method is called to begin a new search. The queryargument supplies the search term. Upon completion, the object becomes populated with the corresponding set of results, and the registered search completion handler is called. query - supplies the query term used to perform the search returns - n/a |
.setSearchCompleteCallback(object, method, opt_arguments?) | This method is used to register an object and method to notify on the completion of a search. Applications may optionally pass in a context argument using opt_argumentswhich is then passed to the specified method. object - supplies an application level object that defines the context that the specified method will be called in. method - supplies the method to call. For instance, if this method is called as .setSearchCompleteCallback(foo, MyObject.prototype.mySearchCompleteHandler), when a search on this searcher completes, a call to foo.mySearchCompleteHandler(opt_arguments?)is called. returns - n/a |
.setUserDefinedLabel(label) | This method is used to set a user defined label that should be used when this searcher is added to a search control. By calling this function, the user defined label specified will be used in the result section header or tab instead of the standard, built in labels. Expected usage is in conjunction with site restricted searching where it is both appropriate and expected that applications will indicate that they have programmed in restrictions by changing the standard label. label - supplies a user defined label that replaces "Web", "Blog", etc. in the results section header. returns - n/a |
.setUserDefinedClassSuffix(classSuffix) | This method is used to set a user defined class suffix for the search results section, and for the collection of search results produced by this searcher in the search control. The motivation for this method is to allow applications to set unique styling for the results and header of a particular set of search results. Assuming this method is called with a value of "siteSearch", a class of gsc-resultsRoot-siteSearchwill be applied to the DIVelement that wraps the header and results associated with this searcher. Note, this is in addition to the generic gsc-resultsRootclass. classSuffix - supplies a user defined class suffix that is appended to gsc-resultsRoot-. This class is added to the DIVelement that wraps the header and results associated with this searcher. returns - n/a |
.setLinkTarget(linkTarget) | This method is called to set the link target used for links embedded in search results. The default value is GSearchgoogle.search.Search.LINK_TARGET_BLANKwhich specifies that links will open in a new browser window. When a searcher is added to a search control, the search control makes an implicit call to this method using the current link target setting for the search control. This means that if your application needs a searcher to operate with a different link target setting than the setting established by the search control, you need to call this method after adding the searcher to the search control. linkTarget - supplies the target frame that links should open within, valid values include: GSearchgoogle.search.Search.LINK_TARGET_BLANK- links will open in a new window, e.g., <A href=... target=_blank ...> GSearchgoogle.search.Search.LINK_TARGET_SELF- links will open in the same window and frame, e.g., <A href=... target=_self ...> GSearchgoogle.search.Search.LINK_TARGET_TOP- links will open in the topmost frame, e.g., <A href=... target=_top ...> GSearchgoogle.search.Search.LINK_TARGET_PARENT- links will open in either the topmost frame, or replace the current frame, e.g., <A href=... target=_parent ...> anything-else - links will open in the specified frame or window, e.g., <A href=... target=anything-else ...> returns - n/a |
.setNoHtmlGeneration() | There are times when your application is not using the search control and is only using a small set of properties from a search result and you are displaying these in a highly customized format. When this is the case, a small optimization is available to your application. The searcher can be programmed to NOT generate an .html property leaving you with only the raw properties valid in a result. n/a - no input arguments returns - n/a |
.setQueryAddition(term) | This method allows the caller to set (or clear) an optional, additional query term that is appended to all queries flowing through the searcher. Applications will typically use this to the provide alternative results with mild variations from the original search term. For example, assuming a GwebSearchgoogle.search.WebSearch()based searcher, calling this function as search.setQueryAddition("filetype:pdf");, and then executing a query for "google", will result in the following query "google filetype:pdf". When using this API, we highly recomend using .setUserDefinedLabel()so that you can indicate to your users that their query has been modified. This is the same general advice we give when using .setSiteRestriction(). term - supplies an expression that is appended to each query flowing through this searcher (note, you do not need to supply a space). When the value of term is "", the effect of this API is canceled; queries are not modified. returns - n/a |
.createResultHtml(result) | This method allows the caller to either create or re-generate the .htmlproperty of the specified result. Sometimes this is needed when the caller had previously used .setNoHtmlGeneration(), or when the caller is reloading a result object from its own storage system. result - supplies a result object. It's .htmlproperty will be deleted and regenerated as a result of this call. If the result does not contain a .htmlproperty, one will be created. returns - n/a |
.gotoPage(page) | After a search completes, a cursorproperty may become visible on the searcher option. This is a function of the number of search results available as well as the capabilities of the underlying searcher. If the cursor property is present, then this method allows you to fetch another bundle of search results. Applications specify which page by using the pageargument. This value is then used to index the cursor.pagesarray which ultimately is used to compute the value of the &starturl argument. page - supplies the page number of the results that the application wants. This value is range checked relative to the .cursor.pagesproperty and no operation is performed if the page is out of range or if the underlying searcher does not have a cursorproperty. returns - n/a |
GSearchgoogle.search.Search - Static methods
Static method | Description |
---|---|
.scaleImage(width, height, imageScaler, opt_img) | This method is a static helper function that you can use to proportionally scale an image. You pass in the width and height of the current image, as well as an imageScaler object (containing a .width and .height property) and the function will calculate and return a proportionally scaled imageScaler object. You can then use this object's .height and .width property to build an image element. Internally, the GvideoSearchgoogle.search.VideoSearch object defines an image scaler which it uses to scale the thumbnails. It's designed to maintain a 4x3 aspect ratio and is defined as follows. // imageScaling defaults 4x3 100x75 image this.imageScaler = {width:100,height:75}; When building the thumbnail imgelement, it computes the scaled height and width of the thumbnail image as follows: // scale the thumbnail image using the searcher's .imageScaler. // By default this is a 4x3 100x75 image, // but its settable using .setVideoResultsTbHeight as well var scaled = GSearchgoogle.search.Search.scaleImage(result.tbWidth, result.tbHeight, this.imageScaler); // scaled.height and scaled.width now contain // the values needed to proportionally scale the thumbnail width - the original width of the image height - the original height of the image imageScaler - an imageScaler object which specifies in its .heightproperty and its .widthproperty the desired height/width box that the image should fit within. opt_img - supplies and optional img object. If specified, its .heightand .widthproperties are set by this call. returns - an imageScaler object whose .heightand .widthproperties contain the dimensions of the proportionally scaled image |
.getBranding(opt_element?, opt_orientation?) | This method is a static helper function that returns a "powered by Google" HTML DOM branding node to your application, and optionally attaches it to your document as the only child of the specified optional element. The purpose of this method is to ensure that your application has a simple way to comply with branding requirements in situations where using with the search form in the GSearchControlgoogle.search.SearchControlor in the GSearchFormgoogle.search.SearchFormis not appropriate for your application. The branding node, by default, is designed for a horizontal orientation and works well underneath a search form, above or below a collection of results, etc. In some cases, a vertical orientation of the branding is needed. As an example of this, consider a vertically oriented Video Bar. In this case, since the branding needs are so narrow, vertical orientation of the branding is needed (see the "powered by Google" branding at the bottom of the Video Bar). This API by default delivers horizontal orientation, but as an application, you can easily request vertical. opt_element - an optional argument which, if supplied, specifies the HTML DOM node that will be populated with a "powered by Google" branding element. opt_orientation - an optional argument which, if supplied, specifies the orientation of the branding node. Valid values include: GSearchgoogle.search.Search.HORIZONTAL_BRANDING - request horizontal orientation GSearchgoogle.search.Search.VERTICAL_BRANDING - request vertical orientation returns - a "powered by Google" HTML DOM node that you are free to attach or clone onto your document. |
.setOnLoadCallback(handler) | This method is a static helper function that registers the specified handler function to be called once the document containing this call loads. Previous documentation recomended that you use the body element's onload attribute (e.g., <body onload="OnLoad()">). While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes that destroy your body.onload handler. The setOnLoadCallback()approach does not have these problems and therefore is our recomended way of registiring a callback that calls your code upon document load (a point in time when the Search APIs are fully loaded and ready for use). handler - a required function that will be called once the containing document is loaded and when the search API is ready for use. returns - n/a |
GSearchgoogle.search.Search - Properties
The following collection of public properties are exposed by all objects that implement this interface. Unless otherwise stated, these properties are assumed to be read-only.Property | Description |
---|---|
.results[] | This property contains an array of search result objects, one for each result. Each time a search executes, this property is cleared, and each time a search completes, the array is populated. If there are no results to report, the .lengthproperty of this array will be set to 0. |
.cursor | This optional property is present once a search completes successfully. When present, the property specifies how an application can request additional search results for the current query term, the estimated result count, the current page, and the url that can be used to vector to a search results page hosted at Google. The property has the following structure: .pages[]- supplies an array used by .gotoPage()in order to retrieve a bundle of results. Each entry in the array is an object with the following structure: .start- supplies the value that will be used in the &starturl argument to request a bundle of results .label- supplies a text label associated with the entry e.g., "1", "2", "3", or "4" .estimatedResultCount- supplies the estimated number of results that match the current query. Note that this value will not necessarily match the similar value thats visible on the Google.com search properties. .currentPageIndex- supplies the index into the pagesarray of the current set of results. .moreResultsUrl- supplies a url to a Google hosted search page that contains additional search results. Note: Web Search supports 8 pages, for a maximum total of 64 results. |
GwebSearchgoogle.search.WebSearch
This object implements theGSearchgoogle.search.Searchinterface over the Google Web Search service. Upon completion of a search it delivers a collection of
GwebResultobjects.
GwebSearchgoogle.search.WebSearch - Constructor
Constructor | Description |
---|---|
GwebSearchgoogle.search.WebSearch() | The constructor is used to create an instance of a searcher object designed to provide search results from the Google Web Search service. |
GwebSearchgoogle.search.WebSearch - Methods
Method | Description |
---|---|
.setSiteRestriction(site, opt_refinement, opt_moreResultsTemplate) | This method is used to restrict the set of web search results returned by this searcher. To restrict to www.amazon.com, simply call this method passing in a value of "www.amazon.com". To clear site restrictions, pass in a value of null. The following snippet demonstrates this setting of a set restriction to "amazon.com". var siteSearch = new GwebSearchgoogle.search.WebSearch(); siteSearch.setSiteRestriction("amazon.com");This method also allows the caller to restrict searches to a Google Custom Search Engine. Instead of specifying a URL path to this method, pass in the Custom Search Engine ID. The following snippet demonstrates setting a site restriction to a custom search engine whose id is 000455696194071821846:reviews. var siteSearch = new GwebSearchgoogle.search.WebSearch(); siteSearch.setSiteRestriction("000455696194071821846:reviews");When used in this manner, an optional Custom Search Engine Refinement may be supplied using the opt_refinement. Using this mechanism you are able to site restrict to a subset of your search engine. The value specified in opt_refinementmust match a Custom Search Engine Refinement label associated with the specified search engine (see the code snippet below). var cseId = "017576662512468239146:omuauf_lfve"; var siteSearch = new GwebSearchgoogle.search.WebSearch(); siteSearch.setSiteRestriction(cseId, "Lectures");Custom search engines often include a customized search results landing page. In order to support this, when Custom Search Engine site restrictions are in effect, an optional opt_moreResultsTemplatevalue may be supplied. This specifies a URL template that will be used to generate the "More results" link at the bottom of a set of search results. The URL template must include a placeholder of "__QUERY__" and "__HL__". When generating the "More results" link, the system will replace these placeholders with the current query term and UI language. The latest addition to Custom Search Engines is the ability to use Linked Custom Search Engines. In order to support this, the siteargument has been extended so that it supports all of the options and modes listed above, in addition to the new anonymous object mode of specifying a site restriction. When the siteargument is an object, one of the following properties may be present (listed in priority order meaning that if you supply multiple properties, the first one that we test for, in the order listed below, wins): siteUrl- The search is relative to the supplied url cseId- The search is relative to the supplied custom search engine id (e.g., 000455696194071821846:reviews) crefUrl- The search is relative to linked custom search engine pointed to by the supplied url. When either cseIdor crefUrlis specified, an optional Custom Search Engine Refinement may be supplied using the opt_refinement. Using this mechanism you are able to site restrict to a subset of your search engine. The value specified in opt_refinementmust match a Custom Search Engine Refinement label associated with the specified search engine (see the code snippet below). searcher = new google.search.WebSearch(); searcher.setSiteRestriction( { crefUrl : "http://www.google.com/cse/samples/vegetarian.xml" }, "recipes");site - supplies a site restriction setting in the form of a partial url (e.g., "www.amazon.com", "google.com", etc.), or a custom search engine id (e.g., "000455696194071821846:reviews", "000455696194071821846:shopping", etc.) Alternatively, this can contain an anonymous object as described above. opt_refinement - when siterefers to a Custom Search Engine, the value of this optional argument specifies a Custom Search Engine Refinement opt_moreResultsTemplate - when siterefers to a Custom Search Engine, the value of this optional argument specifies a URL template that will be used to construct the "More results" link that appears underneath a set of search results in the search control. The URL template must include a placeholder of "__QUERY__" and "__HL__". When generating the "More results" link, the system will replace these placeholders with the current query term and UI language. returns - n/a |
.setRestriction(type, opt_value) | This method is used to specify or clear a restriction on the set of results returned by this searcher. In order to establish a restriction, both typeand opt_valuemust be supplied and valid. In order to clear a restriction, supply a valid value for typeand either specify nullfor the value of opt_value, or do not supply this. This API currently supports the following restriction types: GSearchgoogle.search.Search.RESTRICT_SAFESEARCH- When this is specified as the value of type, the web search results will be restricted to images based on the safesearch value. Valid optional values for this type are as follows: GSearchgoogle.search.Search.SAFESEARCH_STRICT- apply strict filtering for both explicit text and explicit images (the default behavior) GSearchgoogle.search.Search.SAFESEARCH_MODERATE- apply filtering for explicit images GSearchgoogle.search.Search.SAFESEARCH_OFF- do not apply safe search filtering The following code snippet demonstrates how to turn safe search filtering off. var searcher = new google.search.WebSearch(); searcher.setRestriction(google.search.Search.RESTRICT_SAFESEARCH, google.search.Search.SAFESEARCH_OFF); GSearchgoogle.search.Search.RESTRICT_EXTENDED_ARGSNew Args! - When this is specified, the value is an object containing name value pairs where the name may be one of lr, gl, or filterand the value for each is the value associated with the cgi argument as documented below. For example, the following code seqence restricts a web searcher to German and turns off the duplicate content filter searcher = new google.search.WebSearch() searcher.setRestriction(google.search.Search.RESTRICT_EXTENDED_ARGS, { "lr" : "lang_de", "filter" : "0"}); |
Result Objects
Result objects are produced using a JSON encoding of server search requests. As a result, we have chosen not to implement formal Javascript objects, and instead dynamically create these objects from their serialized form. While there is no formal implementation of the objects, they exist, and we document them as if there was a backing Javascript implementation. The impact of all this is minimal. All that it means is that there is no named constructor. For each result, it's as if the system callednew Object()and then proceeded to set formal properties on that object. The results are documented below in terms of their properties.
For all objects, there are two common properties:
.GsearchResultClass- specifies the type of result.
.html- supplies the root of an html element that may be cloned and attached somewhere into the application's DOM hierarchy.
Result Styling
The.htmlproperty discussed above is built with CSS styling in mind. As a result, each piece of semantic information is enclosed in HTML markup with an appropriate set of class markers. This allows you to use this HTML in conjunction with your own custom CSS rules that style the HTML to meet your needs.
As you will see in the sections that follow, each search result is enclosed in a
divelement marked with a generic search result class of
gs-result, as well as a result type specific class e.g.,
gs-webResult,
gs-localResult, etc. This structure allows you to easily define generic CSS rules that are applied to all results, as well as type specific rules.
In addition to this structure, when a result is managed by the
GSearchControlgoogle.search.SearchControl, each result is enclosed in a
divelement marked with a generic search control result class of
gsc-result, as well as a result type specific class e.g.,
gsc-webResult,
gsc-localResult, etc. Each section of results is further wrapped in a
divelement marked with a generic search control results class of
gsc-results, as well as a result type specific class e.g.,
gsc-webResult,
gsc-localResult, etc.
The net result of this structure is the following skeleton:
<!-- A collection of web search results in the search control --> <div class="gsc-results gsc-webResult"> <!-- A single web result in the search control --> <div class="gsc-result gsc-webResult"> <!-- A single web result, full structure defined below --> <div class="gs-result gs-webResult"></div> </div> ... </div> <!-- Similar pattern for local, blog, etc. --> <div class="gsc-results gsc-localResult"></div> <div class="gsc-results gsc-blogResult"></div>
Result Object - Common Properties
Common Property | Description |
---|---|
.GsearchResultClass | Indicates the "type" of result. GwebSearchgoogle.search.WebSearch.RESULT_CLASS- indicates GwebResult |
.html | Supplies the root of an html element that may be cloned and attached somewhere into the application's DOM hierarchy. We expect that this is the primary property that applications will be concerned with and that their typical interaction will involve cloning this node and attaching it into their DOM hierarchy. We expect that they will use css to control styling and to control which elements are displayed. For instance, we expect the following fragment to be common across all applications that wish to copy and paste search results delivered through the Google Search API. // clone the .html node from the result var node = result.html.cloneNode(true); // attach the node into my dom container.appendChild(node); |
GwebResult
This object is produced by theGwebSearchgoogle.search.WebSearchobject. It is available in that object's
.results[]array.
This object is indicated by a
.GsearchResultClassvalue of
GwebSearchgoogle.search.WebSearch.RESULT_CLASS.
GwebResult - Properties
In addition to the common properties described above, the following object specific properties are available.Property | Description |
---|---|
.unescapedUrl | Supplies the raw URL of the result. |
.url | Supplies an escaped version of the above URL. |
.visibleUrl | Supplies a shortened version of the URL associated with the result. Typically displayed in green, stripped of a protocol and path. |
.title | Supplies the title value of the result. |
.titleNoFormatting | Supplies the title, but unlike .title, this property is stripped of html markup (e.g., <b>, <i>, etc.). |
.content | Supplies a brief snippet of information from the page associated with the search result. |
.cacheUrl | Supplies a url to Google's cached version of the page responsible for producing this result. This property may be null indicating that there is no cache, and it might be out of date in cases where the search result has been saved and in the mean time, the cache has gone stale. For best results, this property should not be persisted. |
GwebResult CSS Structure
The following fragment of HTML illustrates the structure of a Web Search result's.htmlproperty. The purpose of this skeleton is to show you the major structural components so that you can alter the styling and display of a result. For instance, if you want to supress the "snippet", a CSS rule of
#mycontrol .gs-webResult .gs-snippet { display : none; }would do the trick.
<div class="gs-result gs-webResult"> <!-- Note, a.gs-title can have embedded HTML // so make sure to account for this in your rules. // For instance, to change the title color to red, // use a rule like this: // a.gs-title, a.gs-title * { color : red; } --> <div class="gs-title"> <a class="gs-title"></a> </div> <div class="gs-snippet"></div> <!-- The default CSS rule has the -short URL visible and // the -long URL hidden. // // If you want to reverse this, use a rule like: // #mycontrol .gs-webResult .gs-visibleUrl-short { display:none; } // #mycontrol .gs-webResult .gs-visibleUrl-long { display:block; } --> <div class="gs-visibleUrl gs-visibleUrl-short"></div> <div class="gs-visibleUrl gs-visibleUrl-long"></div> </div>
Flash and other Non-Javascript Environments
For Flash developers, and those developers that have a need to access the Search API from other Non-Javascript environments, the API exposes a simple RESTful interface. In all cases, the method supported isGETand the response format is a JSON encoded result set with embedded status codes. Applications that use this interface must abide by all existing terms of service. An area to pay special attention to relates to correctly identifying yourself in your requests. Applications MUST always include a valid and accurate http referer header in their requests. In addition, we ask, but do not require, that each request contains a valid API Key. By providing a key, your application provides us with a secondary identification mechanism that is useful should we need to contact you in order to correct any problems. Read more about the usefulness of having an API key Developers are also encouraged to make use of the
useripparameter (see below) to supply the IP address of the end-user on whose behalf you are making the API request. Doing so will help distinguish this legitimate server-side traffic from traffic which doesn't come from an end-user.
Like the core Javascript interface, this interface is exposed through a uniform URL containing a mix of both standard and searcher specific CGI arguments. Your application can use an http stack of it's choosing. The only requirements are that you must be able to construct a properly constructed URL with all necessary CGI arguments, that you send an http referer header that accurately identifies your application, and that you are able to process the JSON encoded response.
Standard URL Base Address'
Each search endpoint is accessed through a standard URL. The following table lists the URL used to access each service.Searcher | Base Url |
---|---|
Web Search | https://ajax.googleapis.com/ajax/services/search/web |
Standard URL Arguments
Each request contains a mix of standard URL arguments and an optional set of searcher specific arguments. This section describes the standard arguments that are uniform across all searchers and that convey virtually identical semantic information to each searcher. In some cases, an argument is optional. This is indicated with a?following the name of the argument. In all cases, the value of a CGI argument must be properly escaped (e.g., via the functional equivalent of Javascript's
encodeURIComponent()method).
The following table lists the standard URL arguments. Additional sections appear below that highlight searcher specific arguments.
Argument | Example | Description |
---|---|---|
q | q=Paris%20Hilton | This argument supplies the query, or search expression, that is passed into the searcher. |
v | v=1.0 | This argument supplies protocol version number. The only valid value at this point in time is 1.0. |
userip? | userip=192.168.0.1 | This argument supplies the IP address of the end-user on whose behalf the request is being made. Requests that include it are less likely to be mistaken for abuse. In choosing to utilize this parameter, please be sure that you're in compliance with any local laws, including any laws relating to disclosure of personal information being sent. |
rsz? | rsz=4 | This optional argument supplies the number of results that the application would like to recieve. Values can be any integer between 1and 8. Alternately, a value of smallindicates a small result set size or 4results. A value of largeindicates a large result set or 8results. Finally, for filter Custom Search Engines, a value of filtered_csewill return 10results. If this argument is not supplied, a value of smallis assumed. |
hl? | hl=fr | This optional argument supplies the host language of the application making the request. If this argument is not present then the system will choose a value based on the value of the Accept-Languagehttp header. If this header is not present, a value of enis assumed. |
key? | key=your-key | This optional argument supplies the application's key. If specified, it must be a valid key associated with your site which is validated against the passed referer header. The advantage of supplying a key is so that we can identify and contact you should something go wrong with your application. Without a key, we will still take the same appropriate measures on our side, but we will not be able to contact you. It is definitely best for you to pass a key. |
start? | start=4 | This optional argument supplies the start index of the first search result. Each successful response contains a cursorobject (see below) which includes an array of pages. The startproperty for a page may be used as a valid value for this argument. For reference, a sample cursor object is shown below: "cursor": { "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12","label": 4 } ], "estimatedResultCount": "48758", "currentPageIndex": 0, "moreResultsUrl": "http://www.google.com/search..." } |
callback? | callback=foo | This optional argument alters the standard response format. When supplied, instead of producing a simple JSON encoded object, the system produces a Javascript function call response where the value of callbackspecifies the name of the function called in the response. callbackFunction( {"responseData" : { "results" : [], "cursor" : {} }, "responseDetails" : null | string-on-error, "responseStatus" : 200 | error-code }); |
context? | context=bar | This optional argument is related to the contextargument. When both are supplied, the value of contextalters the normal response format associated with callback. The new format is: callbackFunction( contextValue, // the context arg value responseObject, // the collection of results and cursor responseStatus, // 200 on success, non-200 on failure errorDetails) // error string for non-200 response |
Standard Response Format
As discussed briefly in the previous section, there are two major variations in the response format. When thecallbackand
contextarguments are not supplied, the response format is a simple JSON object:
{ "responseData" : { "results" : [], "cursor" : {} }, "responseDetails" : null | string-on-error, "responseStatus" : 200 | error-code }
In the JSON fragment above, note that the
responseDataproperty contains a
resultsarray and an optional
cursor. These are identical both semantically and structurally to the results returned through the JavaScript Searchers layer. The
responseStatusproperty contains a value of
200on success and a non-200 http error status code on failure. If there is a failure,
responseDetailscontains a diagnostic string. By using the
callbackargument, applications can easily request a JavaScript callback::
callback({ "responseData" : { "results" : [], "cursor" : {} }, "responseDetails" : null | string-on-error, "responseStatus" : 200 | error-code });
If the application supplies both
callbackand
contextarguments, the response is encoded as a JavaScript procedure call. In this mode of operation, the value of
callbackbecomes the procedure call target, the value of
contextis passes as the first argument, the value of
responseDatafrom above is passes as the second argument, the response status is passed as the third argument, and the final argument is either
nullor a diagnostic string.
foo('bar',{ "results": [ { "GsearchResultClass": "GwebSearch", "unescapedUrl": "http://en.wikipedia.org/wiki/Paris_Hilton", "url": "http://en.wikipedia.org/wiki/Paris_Hilton", "visibleUrl": "en.wikipedia.org", "cacheUrl": "http://www.google.com/search?q\u003dcache:TwrPfhd22hYJ:en.wikipedia.org", "title": "\u003cb\u003eParis Hilton\u003c/b\u003e - Wikipedia, the free encyclopedia", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "content": "In 2006, she released her debut album \u003cb\u003eParis\u003c/b\u003e..." }, { "GsearchResultClass": "GwebSearch", "unescapedUrl": "http://www.imdb.com/name/nm0385296/", "url": "http://www.imdb.com/name/nm0385296/", "visibleUrl": "www.imdb.com", "cacheUrl": "http://www.google.com/search?q\u003dcache:1i34KkqnsooJ:www.imdb.com", "title": "\u003cb\u003eParis Hilton\u003c/b\u003e", "titleNoFormatting": "Paris Hilton", "content": "Self: Zoolander. Socialite \u003cb\u003eParis Hilton\u003c/b\u003e was..." }, ... ], "cursor": { "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12","label": 4 } ], "estimatedResultCount": "59600000", "currentPageIndex": 0, "moreResultsUrl": "http://www.google.com/search?oe\u003dutf8..." } } , 200, null)
Web Search Specific Arguments
The Web Search system supports a number of optional arguments which are all listed below:Argument | Description |
---|---|
cx? | This optional argument supplies the unique id for the Custom Search Engine that should be used for this request (e.g., cx=000455696194071821846:reviews). |
cref? | This optional argument supplies the url of a linked Custom Search Engine specification that should be used to satisfy this request (e.g., cref=http%3A%2F%2Fwww.google.com%2Fcse%2Fsamples%2Fvegetarian.xml). |
safe? | This optional argument supplies the search safety level which may be one of: safe=active- enables the highest level of safe search filtering safe=moderate- enables moderate safe search filtering (default) safe=off- disables safe search filtering |
lr? | This optional argument allows the caller to restrict the search to documents written in a particular language (e.g., lr=lang_ja). This list contains the permissible set of values. |
filter? New! | This optional argument controls turning on or off the duplicate content filter: filter=0- Turns off the duplicate content filter filter=1- Turns on the duplicate content filter (default) |
gl? New! | This optional argument allows the caller to tailor the results to a specific country. The value should be a valid country code (e.g. uk, de, etc.). If this argument is not present, then the system will use a value based on the domain used to load the API (e.g. https://www.google.com/jsapi). If the API loader was not used, a value of "us" is assumed. |
Searcher and Drawing Options
GsearcherOptionsgoogle.search.SearcherOptions
When adding a searcher to the search control, theGsearcherOptionsgoogle.search.SearcherOptionsobject may be specified. If it is, it supplies various options used to control certain aspects of the related searcher. This object is implemented mainly as a property bag which is only loosley connected to a certain class of searcher. Some of its properties apply uniformly to all searchers, while some apply only to specific types of searchers. It is up to the application to use this properly, setting the right options and using them in the proper way.
This object allows the caller to control the default expansion mode (i.e., how the search results are displayed in the searchers section upon search completion), where on the web page the search results are displayed, as well as a variety of searcher specific options. The fragment that follows demonstrates how to use the searcher options class to set searcher options.
// create a searcher options object // set up for open expansion mode // load a searcher with these options var options = new GsearcherOptionsgoogle.search.SearcherOptions(); options.setExpandMode(GSearchControlgoogle.search.SearchControl.EXPAND_MODE_OPEN); searchControl.addSearcher(new GwebSearchgoogle.search.WebSearch(), options);Once a searcher options object has been used in an
.addSearcher()call, changing its properties has an undefined effect. The intended use is to set up an options object, use it when adding a searcher, and then never touch it again.
GsearcherOptionsgoogle.search.SearcherOptions - Constructor
Constructor | Description |
---|---|
GsearcherOptionsgoogle.search.SearcherOptions() | The constructor is used to create an instance of a searcher options object. This object provides various configuration settings used by the search control. |
GsearcherOptionsgoogle.search.SearcherOptions - Methods
Method | Description |
---|---|
.setExpandMode(expandMode) | This method is used to communicate to the searcher the desired expansion mode of results, upon search completion. expandMode - supplies the expansion mode for the associated searcher results section. Valid values include: GSearchControlgoogle.search.SearchControl.EXPAND_MODE_CLOSED- The results section is closed showing no results. Clicking on the twiddle allows the user to "open" the results section seeing all results returned for the current search. GSearchControlgoogle.search.SearchControl.EXPAND_MODE_OPEN- The results section is open showing all results. GSearchControlgoogle.search.SearchControl.EXPAND_MODE_PARTIAL- The results section is partially open showing a small fraction of the results. Typically this means that only a single result is displayed. returns - n/a |
.setRoot(element) | This method is used to instruct the search control to draw the search results for the associated searcher in the container element provided rather than in the default container allocated during the execution of the search controls' .draw()method. element - Supplies an html container element, which is typically a divelement, that the search control is to use as a container for the results for the associated searcher. returns - n/a |
.setVideoResultsTbHeight(height) | This method allows the caller to specify an alternate default scaling factor that is applied to video search results as they are displayed by the search control. Note, the height supplied has an impact on the resulting width of the video as well. The system maintains a 4x3 aspect ratio for videos so the resulting width of the video is height * 1.33. The result is an imageScaler object (see GSearchgoogle.search.Search.scaleImage). Using this function has an impact on the .gs-videoResult td div.gs-image-boxCSS rule within gsearch.css, so make sure that if you are adjusting video sizes you make compatible changes to your over-ride of this rule. height - supplies the maximum height, in pixels, that the video's thumbnail should be scaled to before rendering by the search control. A maximum value of 100px is enforced by the API. returns - n/a |
.setImageResultsTbHeight(height) | This method allows the caller to specify an alternate default scaling factor that is applied to image search results as they are displayed by the search control. Note, the height supplied has an impact on the resulting width of the image as well. The system maintains a 4x3 aspect ratio for images so the resulting width of the image is height * 1.33. The result is an imageScaler object (see GSearch.scaleImage). Using this function has an impact on the .gs-imageResultCSS rule (width property) as well as .gs-imageResult .gs-image-boxCSS rule (height property). The default image dimensions are 112x84, hence the 114x86 CSS rules (2px larger to account for a 1px border). Make sure that if you are adjusting image sizes you make compatible changes to your over-ride of these rules. height - supplies the maximum height, in pixels, that the images's thumbnail should be scaled to before rendering by the search control. A maximum value of 100px is enforced by the API. returns - n/a |
.setNoResultsString(str) | Normally, when a search produces no results, the search control slot for the searcher is left empty. This method allows the caller to specify a string that supplies a default "result". The system contains a value of GSearchControlgoogle.search.SearchControl.NO_RESULTS_DEFAULT_STRINGwhich you can use. This is a localized string that means "No Results" in all supported locales. str - supplies a string value that is used when a search yields no results.. returns - n/a |
GdrawOptionsgoogle.search.DrawOptions
When asking a search control to draw, you must specify a container for the control to draw within. In addition to this required parameter, the search control's.draw()method also accepts an optional
GdrawOptionsgoogle.search.DrawOptionsobject. This object allows applications to request linear or tabbed layout (with linear being the default). Additionally, this object allows the application to request that the "search form" (i.e., the input element, button, controls, etc.) associated with driving the search be decoupled from the set of search results. This is accomplished by using the
.setSearchFormRoot()method and supplying a container of your own that should host the search form.
As a more advanced mode of the above, this object allows applications to request that the search control not create a search form at all and instead use an application supplied text input element. When this option is specified, the search control takes control of the input element, grabbing
onkeyupand
onpasteevents. Over time the list of events that the control latches on to may change. By handing an input element to the search control, the application is simply claiming responsibility for placement of the element as well as styling. Once the input element has been handed to the control, the application should not interact with the element other than to read its value if needed.
The following fragment demonstrates how to use this object to request that the search control draw itself in "tabbed" mode.
// create a drawOptions object var drawOptions = new GdrawOptionsgoogle.search.DrawOptions(); drawOptions.setDrawMode(GSearchControlgoogle.search.SearchControl.DRAW_MODE_TABBED); searchControl.draw(element, drawOptions);The following fragment demonstrates how to use this object to request that the search form be decoupled from the set of search results.
... <div id="searchForm">Loading...</div> ... var searchFormElement = document.getElementById("searchForm"); var drawOptions = new GdrawOptionsgoogle.search.DrawOptions(); drawOptions.setSearchFormRoot(searchFormElement); searchControl.draw(element, drawOptions);
GdrawOptions - Constructor
Constructor | Description |
---|---|
GdrawOptionsgoogle.search.DrawOptions() | The constructor is used to create an instance of a draw options object. This object provides various configuration settings used by the search control during its draw phase. Specifically, it provides control over tabbed vs. linear mode, as well as providing an application with a way to hand an input element off to the search control. The default setting for a newly constructed draw options object is linear mode with search control owned/created text input element. |
GdrawOptionsgoogle.search.DrawOptions - Methods
Method | Description |
---|---|
.setInput(inputElement) | This method is used to hand an input element off to the search control. Instead of creating its own text input element for capturing search queries, the control will use this application provided input element. When this option is specified, the search control takes control of the input element, grabbing onkeyupand onpasteevents. Over time the list of events that the control latches on to may change. By handing an input element to the search control, the application is simply claiming responsibility for placement of the element as well as styling. Once the input element has been handed to the control, the application should not interact with the element other than to read its value if needed. inputElement - supplies an input element that should be used by the search control. returns - n/a |
.setDrawMode(drawMode) | This method is used to instruct the search control to draw the search results in either "tabbed" or "linear" mode. drawMode - A value of GSearchControlgoogle.search.SearchControl.DRAW_MODE_LINEARis used to specify linear drawing mode. A value of GSearchControlgoogle.search.SearchControl.DRAW_MODE_TABBEDis used to specify tabbed drawing mode. returns - n/a |
.setSearchFormRoot(element) | This method is used to indicate that you would like the "search form" placed in the DOM container specified by "element" rather than in its default location near the search results. element - supplies a container that the "search form" will be placed within. returns - n/a |
.setAutoComplete(enabled) | Indicate that you would like the key presses in the input box to trigger requests for auto completions on the query typed so far. Before completions will be available, you must configure the custom search engine at www.google.com/cse to enable autocompletions. This feature is currently only available for filter Custom Search Engines. enabled - true to turn on requests for auto complete, false to disable the requests. returns - n/a |
相关文章推荐
- 新的Google Ajax Search Api
- 掌握 Ajax,第 9 部分: 使用 Google Ajax Search API
- iOS6.1地图Search API正式替代Google Places
- 掌握 Ajax,第 9 部分: 使用 Google Ajax Search API
- 实践杂谈(2)-- 图解 Google Customer Search API 使用全流程
- google Image search API
- http://www.ajaxlines.com/ajax/stuff/article/using_google_is_ajax_search_api_with_java.php
- Google 的Search API
- Ajax学习摘录之第九部分 使用 Google Ajax Search API
- Web开放趋势代表:无所不在的Google API
- Google AJAX Search API+TAG=美味的站点
- 新的Google Ajax Search Api
- Google Maps API Web Services文档使用
- 使用Google Ajax Search API
- 新的Google Ajax Search Api
- google应用之 JSON/Atom Custom Search API
- 面向Google、YouTube、Facebook以及其他Web 2.0 API的C#和VB.NET类库
- 掌握 Ajax,第 9 部分: 使用 Google Ajax Search API
- Google Web 字体 API 访谈
- Google Maps API Web Services(一:The Google Geocoding API)