Setting up a Supplemental Search Engine: Step by Step

This article aims to explain each step required to set up a Supplemental Search Engine in SearchWP. The purpose of a Supplemental Search Engine is to allow you to not only establish a fully-configured global search engine for your site, but also set up additional search engines for specific sections and/or pages of your site as well.

Please note that Supplemental Search Engines are powered by the same index your global (default) search engine is, so there is no need to reindex your content after creating a Supplemental Search Engine in SearchWP.

Creating the Supplemental Search Engine

The first step you’ll take is to set up and configure your Supplemental Search Engine. You can do this by navigating to the main SearchWP Settings page found via the main WordPress administration navigation in Settings > SearchWP. At the bottom of the screen will be a section titled Supplemental Search Engines.

Click Add Engine to add a supplemental engine

Begin by clicking the Add New Supplemental Engine button, and you’ll be presented with a familiar configuration screen:

The new supplemental engine (has no configuration by default)

The only difference between the configuration of a Supplemental Search Engine and the default search engine is that each Supplemental Search Engine has a name. You can name each Supplemental Search Engine anything you’d like, it’s simply used for your reference and in the code snippets you’ll be working with later. Click the name of your engine to edit it.

You can then proceed to add post types and fill out keyword weights for each post type as you did for the default search engine. Once complete, click Save Engines at the bottom of the page.

Note that your Supplemental Search Engine now has a machine-compatible name based on the one you populated:

Code-friendly engine name

Supplemental engines use the main index, so making changes may require you to rebuild your index. A message will be presented to you should that be the case.

Setting up the Supplemental Search Engine search form

Out of the box, SearchWP piggybacks the core search form provided with WordPress that utilizes WordPress’ native search. When it comes to Supplemental Search Engines in SearchWP, you will need to create your own search form(s) which will utilize the Supplemental Search Engine you just created. The process of creating a Supplemental Search Engine form is as straightforward as creating any form submission that you may or may not be familiar with.

Step 1: Create the results Page

The most straightforward part of this process will be establishing where you want search results to appear. In other words, we need to define the page that will list the Supplemental Search Engine results. Native WordPress search solves this problem by checking for a GET variable named s, internally checking for the presence of this variable and appropriately loading your theme’s search.php (if present) to show search results.

When it comes to SearchWP’s Supplemental Search Engines, you can control how the results appear using any number of techniques, but the suggested method is to create a new WordPress Page that will be used in conjunction with a custom theme template we will create. For the time being we will only be creating the new WordPress Page itself, the template will be built later in a later step.

Step 2: Create the search form

The next step will be to create and implement the form that will be used to submit search queries to the Supplemental Search Engine. To do so, we’re going to work from the form WordPress uses for native search, but customize it for our use, like so:

	<div class="search-box">
	<form role="search" method="get" class="search-form" action="<?php echo get_permalink( 147 ); ?>">
	<label>
	<span class="screen-reader-text">Search for:</span>
	<input type="search" class="search-field" placeholder="Search …" value="" name="swpquery" title="Search for:">
	</label>
	<input type="submit" class="search-submit" value="Search">
	</form>
	</div>

view raw gistfile1.html hosted with ❤ by GitHub

Take note of the customizations: first the form action. Note that it has been customized such that when submitted, this form is going to direct visitors to the WordPress Page we just created that has an ID of 147.

The other customization that was made was the name of the search field. It has been changed to swpquery, but you can modify this name to be anything that suits your purpose.

This customized form can be placed anywhere in your theme, just as you can place default search forms anywhere within your site. You could also create a Widget out of this code if you’d like, or turn it into a Shortcode. For the purpose of this article, we will be inserting it directly at the top of the same theme template we’ll use to show the search results.

Step 3: Create the search results template

The final step to fully integrating a Supplemental Search Engine into your site will be creating a new theme template that will show search results from the Supplemental Search Engine that you set up. This template will be applied to the results page we created earlier in this walkthrough, and will include the search form from Step 2 at the top. This specific page template will be based on Twenty Fifteen’s page template, but include both the custom search form and another snippet to retrieve the actual search results from SearchWP for our Supplemental Search Engine.

Begin by creating a new file in your theme directory called page-searchwp-supplemental.php with the following content:

	<?php

	/* Template Name: SearchWP Supplemental Search Results */

	global $post;

	// retrieve our search query if applicable
	$query = isset( $_REQUEST['swpquery'] ) ? sanitize_text_field( $_REQUEST['swpquery'] ) : '';

	// retrieve our pagination if applicable
	$swppg = isset( $_REQUEST['swppg'] ) ? absint( $_REQUEST['swppg'] ) : 1;

	if ( class_exists( 'SWP_Query' ) ) {

	$engine = 'bbpress'; // taken from the SearchWP settings screen

	$swp_query = new SWP_Query(
	// see all args at https://searchwp.com/docs/swp_query/
	array(
	's' => $query,
	'engine' => $engine,
	'page' => $swppg,
	)
	);

	// set up pagination
	$pagination = paginate_links( array(
	'format' => '?swppg=%#%',
	'current' => $swppg,
	'total' => $swp_query->max_num_pages,
	) );
	}

	get_header(); ?>

	<section id="primary" class="content-area">
	<main id="main" class="site-main" role="main">

	<header class="page-header">
	<h1 class="page-title">
	<?php if ( ! empty( $query ) ) : ?>
	<?php printf( __( 'Search Results for: %s', 'twentyfifteen' ), $query ); ?>
	<?php else : ?>
	SearchWP Supplemental Search
	<?php endif; ?>
	</h1>

	<!-- begin search form -->
	<div class="search-box">
	<form role="search" method="get" class="search-form" action="<?php echo esc_html( get_permalink() ); ?>">
	<label>
	<span class="screen-reader-text">Search for:</span>
	<input type="search" class="search-field" placeholder="Search..." value="" name="swpquery" title="Search for:">
	</label>
	</form>
	</div>
	<!-- end search form -->

	</header><!-- .page-header -->

	<?php if ( ! empty( $query ) && isset( $swp_query ) && ! empty( $swp_query->posts ) ) {
	foreach ( $swp_query->posts as $post ) {
	setup_postdata( $post );

	// output the result
	?>
	<div class="search-result">
	<h2>
	<a href="<?php echo get_permalink(); ?>">
	<?php the_title(); ?>
	</a>
	<?php the_excerpt(); ?>
	</h2>
	</div>
	<?php
	}

	wp_reset_postdata();

	// pagination
	if ( $swp_query->max_num_pages > 1 ) { ?>
	<div class="navigation pagination" role="navigation">
	<h2 class="screen-reader-text">Posts navigation</h2>
	<div class="nav-links">
	<?php echo wp_kses_post( $pagination ); ?>
	</div>
	</div>
	<?php }
	} else {
	?><p>No results found.</p><?php
	} ?>

	</main><!-- .site-main -->
	</section><!-- .content-area -->

	<?php get_footer();

view raw gistfile1.php hosted with ❤ by GitHub

Note the customizations that were made:

On line 8 we set $query to be the search query (if a search has taken place)
On line 11 we keep track of pagination
On line 15 we define our Supplemental Search Engine name from the earlier step
Lines 26-31 are preparing our pagination
Lines 48 – 57 represent our customized search form
Lines 61 – 91 are our implementation of The Loop using $swp_query->posts as defined on line 17
Lines 80 – 88 output pagination links (if applicable)

Once you have saved this file, return to the edit screen of the WordPress Page that was created to show the search results. Find the box titled Page Attributes on this edit screen, changing the Template to be SearchWP Supplemental Search Results. Apply the change by clicking the Update button as you would after making any edit to the content.

When the page refreshes, you will see the page we have just created with a customized search form that searches the SearchWP Supplemental Search Engine we created. You can customize this theme template in any way that you’d like, making sure to not remove the code specific to retrieving the SearchWP Supplemental Search Engine results.