PMC Custom Google Site Search

PMC_Customized_Google_Site_Search class

PMC_Customized_Google_Site_Search is an abstract class that allows you to implement a customized Google Custom Search box and show the search results on a customized page. It does all the major heavy lifting and requires bare minimum setup for implementation.

Making it work

PMC_Customized_Google_Site_Search is an abstract class & it also implements Singleton pattern by extending Singleton Trait. So any implementation that you do by extending this abstract class would automatically implement Singleton pattern.

Requirements

PMC_Customized_Google_Site_Search requires its child classes to define a protected method by name of _child_init() and two protected properties named $_engines & $_banners as arrays.

_child_init()

This function is run when the child class object is created. By means of this function child classes have a way to run whatever initialization stuff they want to run (specific to a particular child class). This is an abstract function and implementing it in child classes is mandatory. If there is no use for this function in the child class then it can just remain empty.

$_engines

A protected class var by name of $_engines is required of all child classes and it has to be an array. It is mandatory and a deviation would result in a LogicException being thrown.

In this var, a child class must store all the different Google Custom Search Engine IDs (provided by Google, like XXXXXXXXXXXXXXXXXXXXX:AAAAAAAAAAA). This var must be an associative array, with the ID provided by Google being value and name of engine (just for labelling purposes on site) being the corresponding key (in lower case, preferably a single word, must not have any special chars except a hyphen or underscore).

The default search engine must have the key site. This will be used as fall back in cases when an engine is not specified.

$_banners

A protected class var by name of $_banners is required of all child classes and it has to be an array. It is mandatory and a deviation would result in a LogicException being thrown.

In this var, a child class must store relative paths (from site theme's root) to banner images. This var must be an associative array, with the image path being value and name of engine (just for labelling purposes on site) being the corresponding key (in lower case, preferably a single word, must not have any special chars except a hyphen or underscore).

Banner images are allowed only for search engines registered in $_engines. If you register an image in this var associated with a key which does not exist in $_engines then that image would never be used even when called for.

The banner image is automatically shown wherever pmc-custom-search-page-title-banner action is called on the search results page. It outputs an <img> tag with search-page-title-banner class.

Showing Search Results

The class at present assumes that you have a page (created in WordPress) with the slug results to display search results. So the effective URL would be //example.com/results/. The post_content field of this page must not have anything that you would want to display on search results page as that field's value would be overwritten by the class when the page is loaded. Anything extra you want to display must be added to the page template or programmatically using the_content filter.

To-Do: This needs to be cleaned up and the class/plugin should add an endpoint instead to show this page allowing a template override by the site's theme.

For an example look at page-results.php in pmc-variety. It also implements the pmc-custom-search-page-title-banner action for banner images.

Displaying the Search Box

The search box can be displayed anywhere by calling the render_search_box() function. This function accepts two parameters:

1. $options: An associative array containing three values:
   1. search_results_url: The URL of the page where search results are shown. Use _get_search_url() to generate URL by passing it the engine name (as registered in $_engines).
   2. engine_name: The engine name (as registered in $_engines).
   3. search_box_placeholder: The default text to show in the search box.
2. $return: A boolean value. If you want the function to return the HTML then set it to TRUE otherwise the function would print out the form where its called and return nothing. This value is FALSE by default.

Styling the Search Box

The search form can be styled using CSS. It is wrapped in a DIV with class pmc-cgss-container. The text box is assigned the class pmc-cgss-box and the search button has the class pmc-cgss-btn. The template containing the form is in pmc-plugins/pmc-google-site-search-widget/views/custom-google-search-box.php