Google Programmable Search Engine
Integrates Google Programmable Search Engine to search your Drupal site and/or any other sites without requiring a Google API key.
google_cse
Install
composer require 'drupal/google_cse:^5.0'
composer require 'drupal/google_cse:^4.0'
Overview
Google Programmable Search Engine (formerly Google Custom Search Engine) is a powerful module that allows you to replace or supplement Drupal's built-in search with Google's search technology. The module provides an embedded search engine that can search any set of one or more sites, leveraging Google's advanced indexing and ranking algorithms.
The module extends Drupal's core Search module by providing a configurable search plugin. Search results can be displayed directly on your site with JavaScript rendering, or users can be redirected to Google to view results. Multiple layout options are available including overlay, full-width, two-column, compact, and results-only displays.
For sites preferring inline search functionality, the module includes a block that combines a search input with results display on the same page, making it ideal for embedding search functionality within sidebars or content regions. The module also supports extensive customization through Google's data attributes, allowing fine-grained control over search behavior including language restrictions, country filtering, SafeSearch settings, and more.
Features
- Integrates Google Programmable Search Engine without requiring a Google API key
- Extends Drupal core Search module with a configurable search plugin
- Multiple layout options: overlay, full-width, two-column, compact, results-only, and Google-hosted
- Option to display search results on-site (requires JavaScript) or redirect to Google
- Standalone search block for embedding search form with inline results on any page
- Customizable query parameter key for URL flexibility
- Support for Google's data attributes to control search behavior (language, country, SafeSearch, etc.)
- Accessibility improvements including ARIA role attributes on search results
- Optional Google watermark display per branding guidelines
- Custom CSS stylesheet override support
- Prefix and suffix text around search results
- Configurable search input width
- Migration support from Drupal 7 installations
- Multiple search instance support for different search configurations
Use Cases
Replace Drupal's Built-in Search
Set Google Programmable Search as the default search to leverage Google's superior indexing and ranking for your site content. Users get familiar Google-style results with features like autocomplete, while administrators benefit from offloading search indexing to Google.
Multi-site Search Portal
Configure a Google Programmable Search Engine to index multiple websites, then use this module to provide a unified search experience across all your organization's web properties from a single Drupal site.
Embedded Search Block
Place the Google Programmable Search block in a sidebar or content region to provide inline search with results displayed on the same page. Ideal for documentation sites or knowledge bases where users want quick access to search without leaving their current context.
Multilingual Site Search
Use Google's data attributes to restrict or boost search results by language or country. Configure multiple search instances with different language filters for sites with content in multiple languages.
Safe Search for Educational Sites
Enable SafeSearch filtering through data attributes to ensure search results are appropriate for educational or family-friendly websites.
Tips
- Register your search engine at programmablesearchengine.google.com before installing the module
- Use the 'Results only' layout with Drupal's search input for the most seamless integration
- Configure data-safeSearch attribute to 'active' for strict SafeSearch on family-friendly sites
- Use custom CSS to match Google's search results styling with your site's theme
- Multiple search instances can be created for different use cases (e.g., site search vs. documentation search)
- The Google watermark display follows Google's branding guidelines - check their documentation for requirements
- For accessibility compliance, keep the 'Add accessibility improvements' option enabled
- Test search functionality with JavaScript disabled to verify the noscript fallback works correctly
Technical Details
Admin Pages 1
/admin/config/search/pages/add/google_cse_search
Create a new Google Programmable Search page instance. Multiple instances can be created with different configurations.
Permissions 1
Hooks 4
google_cse_form_search_block_form_alter
Alters the core search block form when Google PSE is set as the default search. Configures the search input width, watermark display, and redirects to Google if configured.
google_cse_library_info_build
Dynamically builds library definitions for custom external CSS files configured in search plugins.
google_cse_entity_insert
Clears router cache when a new Google CSE search page entity is created to register the new routes.
google_cse_migration_plugins_alter
Alters migration plugins to include Google CSE configuration migration when upgrading from Drupal 7.
Troubleshooting 5
Ensure JavaScript is enabled in the browser. If results are configured to display 'On this site', JavaScript is required. Also verify the Google Search Engine ID (cx) is correctly entered.
Do not place the Google Programmable Search block on the search results page. The block is designed for embedding on other pages and will conflict with the search page if placed there.
Ensure data attribute keys begin with 'data-' and values contain only alphanumeric characters, underscores, hyphens, and periods. Both key and value must be provided for each attribute.
After changing the query parameter key, clear all Drupal caches. The module automatically rebuilds routes but cached pages may still use the old parameter.
Verify the 'Search input width' configuration is set to a value greater than 0. A value of 0 will use the browser's default input width.
Security Notes 4
- The module validates that URL query parameters for the search engine ID (cx) and SafeSearch settings match the configured values to prevent URL manipulation
- Data attribute values are validated to prevent XSS through alphanumeric-only character restrictions
- Prefix and suffix HTML content undergoes XSS filtering - script tags are stripped while basic HTML is allowed
- Custom CSS URLs should be from trusted sources as they are loaded as external stylesheets