Control Panel

This page discusses how you can customize the look and feel of your search box and search results using the control panel. If you want to implement the design of your search engine using the context file, see the "Designing the Look and Feel with XML page".

Overview
Designing Individual Components of the Search UI
Hosting the Results using the Search Element
Setting the Search Element Layout
Designing the Search Box
Designing the Results
Previewing Your Search Engine
Implementing the Design in Your Website

Overview

You can change both the search box and the search results of your Programmable Search Engine in either the control panel or the XML context file. If you have a handful of search engines, managing and customizing them with the control panel is fairly simple. Just navigate to the Look and feel tab, select a style, design the components, click Save and you are good to go. This page tells you how to do all that. However, if you are creating and managing a large number of search engines, even that simple procedure—when repeated across multiple search engines—gets tedious. In such cases, working with XML would be better. If you decide to use XML, read this page first to get an idea of how things generally work; afterwards, read the Designing the Look and Feel with XML page to learn about the XML elements and attributes.

If you are not sure whether you should just use the control panel or use the XML format, see The Basics page, which discusses the benefits and challenges of each format.

Note: Before you start designing the look and feel of your custom search engine, read the Guidelines for implementing Programmable Search Engine . It's a short document that tells you how you should handle Google branding and attribution.

Hosting the Results using the Search Element

A Search element is an object that you can embed in your webpage, which allows extensive customization. It can show the search box and search results, either together in the same webpage that the reader is viewing or in different webpages.

Note: Search element, when paired with a compact layout, works well on mobile devices.

You can also take advantage of the Programmable Search Element Control API to further customize the search UI. Many customizations are supported through HTML attributes. For example, you can select among six layouts for your results page, or you can set the number of search results to return.

Programmable Search Engine no longer supports the iframe hosting option. We recommend the "Two page" or "Results only" layouts in Search element as the new options. Check out our blog post for more information.

Designing Individual Components of the Search UI

You can customize the look and feel of your search engine by doing the following:

In the Look and feel tab of the control panel, select a search element layout and click the save button.
Under Themes tab, select a theme then click the save button:
If you want to customize the theme, do the following (otherwise, skip to the next step):
1. Click the Customize tab.
2. Select the appropriate controls from the page.
3. Define the new values.
  If you change your mind, you can always revert back to the default values by clicking Reset button. Experiment with the values while previewing the changes.
4. If you've enabled image search, select the layout you want.
5. Click Save.
Use Thumbnail to enable or disable Automatic Thumbnail images in search results.
Implement the design in your website.

The Customizable Components

The components that you can customize depends on the selected Element layout of your search engine. For example, the control panel lets you add a logo only for search engines that are hosted by Google; you cannot add a logo to search engines using other hosting options.

You can define the following components using the control panel:

The Search element layout
The search box
The search results
The refinement tabs
The promotions
The logo (Google-hosted only)

Setting the Search Element Layout

You have the option to customize how your search UI is laid out on the webpage. You can place the search box and the results section in the same column or display them in separately columns with the search box in one column and the results section in another column or even in another page.

Your layout options are (click the links to see demos):

Option	Description
OverLay	Display the search results in an overlay.
Two Page Simple Multiple search boxes/results sections	The search box and the search results section are placed in two different webpages. Note: The search results section also contains a search box. Users can submit queries in the search results page directly.
Full-width	The search box and the search results section take up the entire width of the page or the column where you have inserted the Search element.
Two Column	The search box and the search results section are in different columns or sections of your webpage. To close the search results section, the user clicks on the X icon next to the search box.
Compact	Like the full-width option, this takes up the entire width of the page or column, but the results section shows fewer results, so it takes up less vertical space when expanded in the webpage. Tip: This option is optimized for smartphones and mobile devices.
Results Only Search via URL Search via search box	Search results are placed in one of your webpages, and the search results page does not contain a search box. Use your own search box to submit the search query. Note: A Programmable Search Engine that does not show ads has no option to disable branding. Demo: How to customize branding options
Google-Hosted Current window New window	The search box is placed on one of your webpages. The search results are displayed on a Google-hosted webpage, which can be opened either in the same window or in a new window.

You can insert the search box anywhere within the HTML body of your webpage, although—by convention—search boxes are placed at the top (or close to the top) of webpages, as in the following example:

Figure 1: Webpage with the search box positioned at the top.

To create and design a search box, do the following:

Customize the search box.
Optional. Enable autocompletion.
Implement the search box in your webpages.

You can customize the search box by doing the following in the style tabs:

Change the colors:
1. Select the Search Controls tab.
2. Set the values for the colors of the search box:
  - Search input: Border color - the color of the border around the input field for search queries.
  - Search button: Border color - the color of the border around the search button. The thin lines of the border might not be apparent if the color is similar to that of the button.
  - Search button: Background color - the color of the search button.
3. Click Save.
Change the font style for the search button (and the rest of the element):
1. Select the Global styles tab.
2. In the Text drop-down list, select the font family.
  The setting changes the font of not just the text in the search button, but also the text in the entire element, including the refinement tab and the result snippets.
3. Click Save.

The preview section below the style tabs shows the changes you made in the settings.

Enabling Autocompletion

Autocompletion offers query options to your users as they enter their search queries on your search box. It is similar to the optional queries that you see on Google search.

Figure 2: Typing just a few characters in the search box brings up a drop-down list that provides options for different search queries.

Programmable Search Engine tailors autocompletion specifically to your search engine. It uses a different algorithm that draws from multiple sources, including queries to your search engine, as well as keywords and phrases extracted from the content of websites that your search engine covers.

Because the autocompleted queries are based—in part—on the specific content of the webpages covered by your search engine, Programmable Search Engine does not generate autocompletions for search engines that search the entire web. In other words, only search engines that search included sites—a predetermined collection of websites—can have autocompleted queries. You can set the coverage of your search engine in Sites tab of the control panel.

Unlike the other settings described in this page, autocompletions is not in the Look and Feel tab, but in the Autocompletion section of the control panel.

To enable autocompletions, do the following:

In the control panel, select the Autocompletion tab.
Select Enable autocompletions check box..
Click Save Changes.
Note: Because the autocompleted queries are generated for each search engine, it takes a few hours before autocompletion starts appearing in your search engine.
If you are enabling autocompletions in an existing search engine for the first time, you have to remove the code snippet for the search box that you had inserted in your webpage. Replace it with the new one generated in the Get code tab. For more detailed instructions, see the Implementing the Design in Your Website section.

Designing the Results

You can change the following components of the results page:

The individual results
Image Search Results
The font type
The text colors
The refinement tabs
The promotions
The logo (Google-hosted only)

The Background Color

To change the background color of your entire results, do the following in the style tabs:

Select the Global styles tab.
In the Element styling: Background color selector, pick the color. Alternatively, you can enter the color value in the text box.
Click Save.

You can also change the color of the border that surrounds the entire element by picking the Element styling: Border color selector or typing the color value in the text box.

The Individual Results

If you want to visually delineate individual results or highlight results that are being selected by users, you can define the borders and background for individual results.

Figure 3: Results with individual results delineated and individual result that is highlighted on mouseover.

To change the colors of individual results, do the following in the style tabs:

Select the Results tab.
Define the following values:
- Results (normal state) styling - Each individual result forms a unit of title, result snippet, and link. This setting controls the color for the individual results. If you want to change the background for all the results, see The background Color section.
- Results (hover state) styling - The set of definitions controls the color of the an individual result when the mouse cursor hovers over it.
Click Save.

Image Search Results

Three layouts are available for image search results: Classic, Column, and Popup.

The Font Type

To change the font style of the text in your results, do the following in the style tabs:

Select the Global styles tab.
In the Text drop-down list, select the font family.
The setting changes the font for the entire element, including the search button, the refinement tabs, and the result snippets.
Click Save.

The Text Colors

To change the colors of the text in your results, do the following in the style tabs:

Select the Results tab.
Define the following values:
- Title text colors - this set of definitions controls the colors for the title of the results snippets. The title is the first line of each result.
- Snippet text color - the body of the results snippets. This is the text that provides a small sample of the content of the webpage.
- URL text color - URL at the bottom of each result snippet.
Click Save.

If you have created refinement labels in your search engine, the labels appear as tabs in the Search element. You can use the control panel to change the colors of the refinement tabs.

To customize the refinements tab, go to the style tabs and do the following:

Select the Search Controls tab.
Set the colors for the refinement tabs:
- Refinement tab (normal state) - the set of controls for the refinement labels that are not in focus.
  - Border color - the color of the border around the tabs that are not currently selected. The thin line might not be apparent if the color of the border is similar to the color of the background.
  - Background color - the color of tabs that are not currently selected.
- Refinement tab (selected state): the set of controls for the refinement label that the user has just selected by clicking. The tab that the user has clicked most recently takes the selected state.
  - Border color - the color of the border around the tab that is currently selected.
  - Background color - the color of the tab that is currently selected.
Click Save.

Promotions

If you have created promotions in your search engine, you can change their look and feel in the style tabs. Promotions are a special type of search results that you create.

To customize your promotions, go to the style tabs and do the following:

Select the Promotions tab.
Define the following values:
- Title text colors - this set of definitions controls the colors for the title of the promotion results.
- Snippet text color - the description of the promotion. If your promotion does not have a description, the setting changes nothing.
- URL text color - the URL at the bottom of each promotion.
- Promotion styling - For element only.
Click Save.

The Logo (Google-Hosted Only)

If you are letting Google host your results page, you can choose to include a logo or small image right next to the search box in the search results page. The image has to be a .jpg, .png, or .gif file hosted on a website (your own or from a website that does not have copyright restrictions). You have the option of associating a URL with the image, turning it into a clickable image.

The following is an example of results page with a logo.

Figure 4: Search box with an image

To add or change a logo in your Google-hosted results page, do the following in the style tabs:

Select the Logo tab.
Define the following values:
- Logo URL - The location of the image. The URL must point to an image file, not a webpage (HMTL file) with an image. The image can be in JPG, PNG, or GIF that does not exceed 100 pixels in height and 100 pixels in width.
- Logo link - Optional. If you want the logo to link to a webpage (your homepage, for example), type the URL.
- Logo height - The default value is 100. If your image is larger than 100 x 100 pixels, Custom Search automatically resizes it.
Click Save.

Previewing Your Search Engine

If you enter a query and click Search, you can preview the results, including the refinements and promotions.

Note: To Preview the selected layout and if any customization was performed, the search box can be previewed on the right hand side of Look and Feel, Layout section.

Implementing the Design in Your Website

After you have designed the look and feel of your search engine, you can implement it in your webpage by doing the following:

Click Save & Get Code in any tab of Look and feel.
Copy the code snippet generated in the Get code tab.
If you have selected the two-column layout, copy two pieces of code snippets: one for the search box, and the other for results.
If you have selected two-page layout, type the URL of the webpage that will show the results for your search engine. Type the query parameter name embedded in the url, which is parsed by search results page. Finally, copy the two pieces of code snippets.
The code snippet for results-only layout is for the case where search results are shown in a new page. Type the query parameter name embedded in the url, which is parsed by the search results page. Finally, copy the search results code snippet.
Insert the code in every page where you want a Programmable Search Engine box. You can paste the code anywhere within the <body></body> tag of your webpage.
Note: For the most cross-browser compatibility, it is recommended that your HTML pages use a supported doctype such as<!DOCTYPE html>.

If you are using hover effects for your Search element, your HTML page must use a supported doctype such as <!DOCTYPE html>.
If you have selected the two-column layout, insert the code for the search box in one column and the code for the results in another column.
If you have selected the two-page layout, insert the code for the search box in the webpage where you want the search box to appear, and the code for the results in the webpage where you want the search results to appear.
If you have selected the results-only layout, insert the code snippet in the webpage where you want the search results to appear.