`. Note that it references `test`, the `id` we used to identify the `
`
const myInitCallback = function() {
if (document.readyState == 'complete') {
// Document is ready when Search Element is initialized.
// Render an element with both search box and search results in div with id 'test'.
google.search.cse.element.render(
{
div: "test",
tag: 'search'
});
} else {
// Document is not ready yet, when Search Element is initialized.
google.setOnLoadCallback(function() {
// Render an element with both search box and search results in div with id 'test'.
google.search.cse.element.render(
{
div: "test",
tag: 'search'
});
}, true);
}
};
// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
parsetags: 'explicit',
initializationCallback: myInitCallback
};
Include this HTML to start loading the Search Element. Replace the `cx` value in the
`src` clause with your own `cx`.
### Search Callbacks
The Search Element JavaScript supports six callbacks that operate in the
[search control flow.](https://developers.google.com/custom-search/docs/element#callback-figure)
The search callbacks come in pairs, a web-search callback and matching image-search callback:
- Search Starting
- For image search
- For web search
- Results ready
- For image search
- For web search
- Results rendered
- For image search
- For web search
Like the [initialization callback,](https://developers.google.com/custom-search/docs/element#init-callback) the search callbacks are
configured using entries in the `__gcse` object. This happens as the Search Element
JavaScript starts. Modifications to `__gcse` after startup are ignored.
Each of these callbacks is passed the [`gName`](https://developers.google.com/custom-search/docs/element#gname-attribute) for
the Search Element as an argument.
The `gname` is useful when a page contains more than one search. Give a search
element a `gname` values using the `data-gname` attribute:
```
```
If the HTML doesn't identify the gname, the Search Element JavaScript generates a value that will
remain consistent until the HTML is modified.
#### Image/Web Search-Starting Callback
The search starting callbacks are invoked immediately before the Search Element JavaScript requests
search results from its server. An example use-case would be using the local time of day to
control changes to the query.
```
searchStartingCallback(gname, query)
```
`gname`
: Search Element's identifying string
`query`
: value entered by the user (possibly modified by search
element JavaScript.)
The callback returns the value that should be used as the query for this search. If it returns an
empty string, the return value is ignored and the caller uses the unmodified query.
> [!NOTE]
> **Note:** The callback may freely modify the parameters' values. Such changes do not affect the behavior of the Search Element JavaScript.
Alternatively, you can put the callback function in the `__gcse` object or
dynamically add the callback to the object with JavaScript:
```
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
```
##### Example Search Starting Callback
The example search starting callback in
[Example Search Starting Callback](https://developers.google.com/custom-search/docs/element#search-starting) adds either `morning`
or `afternoon` to the query depending on the time of day.
**Search Starting Callback Example**
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
Install this callback in `window.__gcse:`
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
#### Image/Web Search Results-Ready Callback
These callbacks are invoked immediately before the Search Element JavaScript renders promotions and
results. An example use case would a callback that renders promotions and results in a style that
cannot be specified with normal customization.
```
resultsReadyCallback(gname, query, promos, results, div)
```
`gname`
: Search Element's identifying string
`query`
: query that produced these results
`promos`
: an array of promotion objects, which correspond to matched
[promotions](https://developers.google.com/custom-search/docs/promotions) for the
user's query. See the [promotion object definition](https://developers.google.com/custom-search/docs/element#promotions).
`results`
: an array of result objects. See the
[result object definition](https://developers.google.com/custom-search/docs/element#results).
`div`
: an HTML div positioned in the DOM where the Search Element would ordinarily
place promotions and search results. Normally, the Search Element JavaScript would handle
populating this div, but this callback may choose to stop the automatic rendering of results
and use this `div` to render results itself.
> [!NOTE]
> **Note:** The callback may freely modify the parameters' values. Changes to `gname,` `query,` `promos,` and `results` do not effect the behavior of the Search Element JavaScript, but if the callback returns true, the DOM tree rooted at `div` is displayed.
If this callback returns a `true` value, the Search Element JavaScript skips to its
page-footer work.
##### Example Results Ready Callback
The example `resultsReady` callback in
[Example Results Ready Callback](https://developers.google.com/custom-search/docs/element#results-ready) overrides the default presentation
of promotions and results with a *very* simple replacement.
> [!NOTE]
> **Note:** Try searching for *plants* to trigger promotions.
**Results Ready Callback Example**
const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
const makePromoElt = (promo) => {
const anchor = document.createElement('a');
anchor.href = promo['url'];
anchor.target = '_blank';
anchor.classList.add('gs-title');
const span = document.createElement('span');
span.innerHTML = 'Promo: ' + promo['title'];
anchor.appendChild(span);
return anchor;
};
const makeResultParts = (result) => {
const anchor = document.createElement('a');
anchor.href = result['url'];
anchor.target = '_blank';
anchor.classList.add('gs_title');
anchor.appendChild(document.createTextNode(result['visibleUrl']));
const span = document.createElement('span');
span.innerHTML = ' ' + result['title'];
return [anchor, span];
};
const table = document.createElement('table');
if (promos) {
for (const promo of promos) {
const row = table.insertRow(-1);
const cell = row.insertCell(-1);
cell.appendChild(makePromoElt(promo));
}
resultsDiv.appendChild(table);
resultsDiv.appendChild(document.createElement('br'));
}
if (results) {
const table = document.createElement('table');
for (const result of results) {
const row = table.insertRow(-1);
const cell = row.insertCell(-1);
const \[anchor, span\] = makeResultParts(result);
cell.appendChild(anchor);
const cell2 = row.insertCell(-1);
cell2.appendChild(span);
}
resultsDiv.appendChild(table);
}
return true;
};
Install this callback in `window.__gcse:`
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
ready: myResultsReadyCallback,
},
};
As with the search starting callback, the above is one of many ways to put the callback in the
`__gcse` object.
#### Image/Web Search Results-Rendered Callback
These callbacks are invoked immediately before the Search Element JavaScript renders the page
footer. Example use cases would include a callback that adds result content that the search
element does not display such as a *save this* checkbox or information that is not
automatically rendered, or a callback that adds *for more information* buttons.
If a *results rendered callback* needs information that was in the `promos` and
`results`
parameters of the *results ready callback*, it can pass that between them, like this:
```
callback(gname, query, promoElts, resultElts);
```
`gname`
: Search Element's identifying string
`query`
: search string.
`promoElts`
: an array of the DOM elements containing promotions.
`resultElts`
: an array of the DOM elements containing results.
There is no return value.
> [!NOTE]
> **Note:** Changing the value of `gname` and `query` don't alter the behavior of the Search Element JavaScript, but changes to the entries in `promoElts` and `resultElts` are changes to the DOM.
> [!NOTE]
> **Note:** Only those DOM elements rendered by the Search Element JavaScript itself are passed to the `resultsRendered` callback.
##### Example Results Rendered Callback
The example `resultsRendered` callback in
[Example Results Rendered Callback](https://developers.google.com/custom-search/docs/element#results-rendered) adds a dummy *Keep*
checkbox to each promotion and result.
**Results Rendered Callback Example**
myWebResultsRenderedCallback = function(name, q, promos, results) {
for (const div of promos.concat(results)) {
const innerDiv = document.createElement('div');
innerDiv.appendChild(document.createTextNode('Keep: '));
const checkBox = document.createElement('input');
checkBox.type = 'checkbox';
checkBox.name = 'save';
innerDiv.appendChild(checkBox);
div.insertAdjacentElement('afterbegin', innerDiv);
}
};
Install this callback in `window.__gcse:`
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
rendered: 'myWebResultsRenderedCallback',
},
};
If the *results rendered callback* needs
information that was passed to the *results ready callback* it can pass that data between
the callbacks. The following example shows one of many ways to pass a rating value from
`richSnippet` from the *results ready callback* to the *results rendered
callback.*
> [!NOTE]
> **Note:** Queries that return numerous results from [stackoverflow](https://www.stackoverflow.com) usually find the *structured data* these callbacks use. Try searching for *closure*.
**Example of Results Ready Callback Cooperating with Results Rendered Callback**
const makeTwoPartCallback = () => {
let saveForRenderCallback;
const readyCallback = (name, q, promos, results, resultsDiv) =>
{
saveForRenderCallback = [];
for (const result of results) {
const {
richSnippet: {
answer = []
} = {},
} = result;
const firstAnswer = answer[0];
if (firstAnswer) {
const upVotes = firstAnswer['upvotecount'];
if (upVotes) {
saveForRenderCallback.push(
{upvotes: parseInt(upVotes, 10)}
);
continue;
}
}
saveForRenderCallback.push({});
}
};
const renderedCallback = (name, q, promos, results) => {
for (let i = 0; i < results.length; ++i) {
const div = results[i];
const votes = saveForRenderCallback[i]['upvotes'];
if (votes) {
const innerDiv = document.createElement('div');
innerDiv.innerHTML = '
Upvotes: ' + votes + '';
div.insertAdjacentElement('afterbegin', innerDiv);
}
}
};
return {readyCallback, renderedCallback};
};
Install this callback using code like this while setting up `__gcse`:
const {
readyCallback: webResultsReadyCallback,
renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
ready: webResultsReadyCallback,
rendered: webResultsRenderedCallback,
},
};
##### Example Results Rendered Callback: Opening specific file types in new tab/window
The following callback example can modify search result links after they are rendered to open a specific file in a new tab/page instead of the current window (for example: PDF, Excel or Word). This improves the browsing experience when users do not want to open a file on the same window and move away from the results page.
This callback example identifies PDF links in the search results and sets the `target="_blank"` attribute on PDF links so that they open in a new tab. A `MutationObserver` is used to dynamically handle new results if the page updates. **Note:** You can replace `.pdf` in `handleSearchResults` with any other filetype as per your requirement.
This callback example does not work on Google Hosted and Overlay layouts.
**Opening specific file types in new tab/window**
function handleSearchResults() {
const links = document.querySelectorAll('.gsc-results .gs-title');
links.forEach(link => {
const url = link.href;
if (url?.toLowerCase().endsWith('.pdf')) {
link.setAttribute('target', '_blank');
}
});
}
const myWebResultsRenderedCallback = () => {
// Call handleSearchResults when results are rendered
handleSearchResults();
// Set up a MutationObserver to handle subsequent updates to the results
const observer = new MutationObserver(handleSearchResults);
const searchResultsContainer = document.querySelector('.gsc-results');
if (searchResultsContainer) {
observer.observe(searchResultsContainer, {
childList: true,
subtree: true
});
} else {
console.log('No Results.');
}
};
Install this callback in `window.__gcse:`
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
rendered: myWebResultsRenderedCallback,
},
};
#### More Callback Examples
Additional callback examples can be found in the
[More Callback Examples](https://developers.google.com/custom-search/docs/more_examples) document.
#### Promotion and Result Properties
Using [JSDoc](https://jsdoc.app) notation, these are the properties of
[promotion](https://developers.google.com/custom-search/docs/element#promotions) and [result](https://developers.google.com/custom-search/docs/element#results) objects.
Here, we list all the properties that might be present. The presence of many of the properties
depend on the details of the promotion or search result.
**Promotion Properties**
```
{
content: string,
image: {
height: number,
url: string,
width: number,
},
title: string,
url: string,
visibleUrl: string,
}
```
**Result Object Properties**
```
{
content: string,
contentNoFormatting: string,
contextUrl: string, // For image search results only
fileFormat: string,
image: { // For image search reseults only
height: number,
url: string,
width: number,
},
perResultLabels: !Array<{
anchor: string,
label: string,
labelWithOp: string,
}>,
richSnippet: !Array, // For web search results only
thumbnailImage: {
height: number,
url: string,
width: number,
},
title: string,
titleNoFormatting: string,
url: string,
visibleUrl: string,
}
```
`richSnippet` in [results](https://developers.google.com/custom-search/docs/element#results) has the loose type of an array of
objects. The values of entries in this array are controlled by the
[structured data](https://developers.google.com/custom-search/docs/structured_data)
found on the web page for each search result. For instance, a review web site might include
structured data that adds this array entry to `richSnippet`:
```
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},
```
## Programmable Search Element Control API (V2)
The `google.search.cse.element` object publishes the following
static functions:
| Function | Description |
|---|---|
| `.render(componentConfig, opt_componentConfig)` | Renders a Search Element. **Parameters** | Name | Description | |---|---| | `componentConfig` | The configuration for a Programmable Search Element component. Specifies the following: - `div` (string\|Element): The `id` of the `
` or the `div` element in which the Programmable Search Element is to be rendered. - `tag` (string): The type of component(s) to be rendered. (When [`opt_componentConfig`](https://developers.google.com/custom-search/docs/element#opt_componentConfig) is supplied, the value of the `tag` attribute must be `searchbox`.) Allowed values are: - `search`: A search box and search results, displayed together - `searchbox`: A search box component of a Programmable Search Element. - `searchbox-only`: A standalone search box, which will be paired with a block of search results specified by `opt_componentConfig` in two-column layout. - `searchresults-only`: A standalone block of search results. Searches are triggered by a query parameter embedded in a URL, or by programmatic execution. - `gname` (string): (Optional) A unique name for this component. If not supplied, Programmable Search Engine will automatically generate a `gname`. - `attributes` (Object): Optional attributes in the form of a key:value pair. [Supported attributes.](https://developers.google.com/custom-search/docs/element#supported_attributes) | | `opt_componentConfig` | Optional. Second component configuration argument. Used in `TWO_COLUMN` mode to provide the `searchresults` component. Specifies the following: - `div` (string): The `id` of the `
` or the `div` element in which the element is to be rendered. - `tag` (string): The type of component(s) to be rendered. When `opt_componentConfig` is supplied, the value of the `tag` attribute must be `searchresults`. In addition, the value of the `tag` attribute of [`componentConfig`](https://developers.google.com/custom-search/docs/element#componentConfig) must be `searchbox`. - `gname` (string): (Optional) A unique name for this component. If not supplied, Programmable Search Engine will automatically generate a `gname` for this component. If supplied, it must match the `gname` in `componentConfig`. - `attributes` (Object): Optional attributes in the form of a key:value pair. [Supported attributes.](https://developers.google.com/custom-search/docs/element#supported_attributes) | |
| `.go(opt_container)` | Renders all Search Element tags/classes in the specified container. **Parameters** | Name | Description | |---|---| | `opt_container` | The container containing the Search Element components to render. Specify either the ID of the container (string) or the element itself. If omitted, all Programmable Search Element components inside the page's `body` tag will be rendered. | |
| `.getElement(gname)` | Gets the element object by `gname`. If not found, return null. The returned `element` object has the following attributes: - `gname`: The name of the element object. If not supplied, Programmable Search Engine will automatically generate a `gname` for the object. [More information.](https://developers.google.com/custom-search/docs/element#gname) - `type`: The type of element. - `uiOptions`: The final attributes used to render the element. - `execute` - function(string): Executes a programmatic query. - `prefillQuery` - function(string): Prefills the searchbox with a query string without executing the query. - `getInputQuery` - function(): Gets the current value displayed in the input box. - `clearAllResults` - function(): Clears the control by hiding everything but the search box, if any. The following code executes the query "news" in the Search Element "element1": ``` var element = google.search.cse.element.getElement('element1'); element.execute('news'); ``` |
| `.getAllElements()` | Returns a map of all successfully created element objects, keyed by `gname`. |