WordPress.org

Ready to get started?Download WordPress

Plugin Directory

!This plugin hasn't been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues when used with more recent versions of WordPress.

Search API

Search API is a set of functions that allows developers to easily implement new search functionality for WordPress. A set of plugins to enhance the se

TO-DO

  • Final Code Sweap

Issue Tracker

WordPress Search API has an issue tracker. Please submit any bug reports or feature suggestions here.

Developer Tutorial

Note: This tutorial is not complete. The data in this tutorial is complete but has not been proofread and still needs to be edited.

Introduction

This section will show developers how to create a new search plugin that uses the Search API. The tutorial assumes that we are building the the base for the Sphinx search plugin.

Before starting you should become familar with writing WordPress plugins by reading the Writing a Plugin WordPress Codex entry. A search API plugin is a WordPress plugin that is loaded after the Search API plugin is loaded.

Tutorial

First grab the PHP Documentation (PHPDocumentor Documentation) for this project to learn some more about the classes, functions, and variables within the project. The documents in this archive will provide you with some background on the source code before we start working with it.

Next download a dummy plugin that contains the basic plugin elements. This tutorial will take a look at what each line (minus extra phpdoc comments) does and will discuss how to make a few changes to improve the functionality of the plugin.

Download the dummy file.

The first lines in the file are a standard comment block containing some information for WordPress to read. The data here are used for displaying the name of the plugin in both the admin control panel and in the wordpress.org plugin directory if you choose to upload it there.

<?php
/*
Plugin Name: NAME
Plugin URI: PLUGIN URL
Description: DESCRIPTION
Author: AUTHOR NAME
Version: VERSION
*/

The WordPress Codex contains additional information on how to format the file header.

The next lines define the class our methods will be wrapped in. The offical search plugins follow the standard convention of SOMENAME_search where SOMENAME is mysql, google, or sphinx. In this case, we would replace dummy with sphinx or another unique and descriptive name.

class sphinx_search
{

Next we define two required variables that hold basically share data between the Search API and the search plugin.

var $results = array();
var $flags = array();

The first is an array of results. If we are pulling data from a database it is usually in the form of a WP-DB result set. Note: The plugin you create does not need to actually use this variable (the Google plugin simply echos out the results in the form of an iframe).

The second is an array of flags (query operators) such as start date for searching, keywords, categories to search in, and so on. The Search API populates this array for you so you only need to define it.

The following flags can be used later on in the search plugin:

$this->flags['string']      A simple escaped value of the query string 's'
$this->flags['terms']       An array of each term in the above string (separated by spaces)
$this->flags['startYear']   The year to begin searching for documentes (Say you only want to search 2008-2009, 2008 would be the value here)
$this->flags['startMonth']  The month to begin searching for documents.
$this->flags['startDay']    The day to begin searching for documents.
... as well as endYear, endMonth and endDay.
$this->flags['author']      The author name (admin, justin, etc) and not the ID
$this->flags['categories']  An array of categories to search in     
$this->flags['types']       An array of the types of content to search (i.e., posts, pages, or comments or an empty array/value for all)        
$this->flags['sort']        How to sort the content (relevance, date, or alpha)     
$this->flags['sorttype']    Sort order (DESC or ASC)
$this->flags['page']        The page of results we are on for LIMIT queries, etc.

$this->flags['tags'] The taxonomy tags to search for

Next we define a set of options and features our plugin will use. The Search API allows you to disable options and features you do not need. For example, we disable the search indexing feature on the Google plugin because it is a waste of processing power if Google is already indexing.

var $options = array(
            'advanced' => 0,
            'filters' => 0,
            'sort' => 0,
            'pagination' => 0,
            'index' => 0,
        );

In order by the listing in code:

The first line enables an advanced search page which allows you to have a dedicated page for searching with extended options (like a category picker). We will want this for the Sphinx plugin or most plugins.

The next line, enables or disables filters, which are simply options for filtering by content type (posts, pages, comments) on the search results page under the search box. We will enable this for most plugins.

The next line, enables or disables sorting on the search results page. We enable this for most plugins.

This line sets pagination, which is useful for large blogs and working with database systems. The sphinx plugin and most database plugins will use this so set the value to 1

This last line sets indexing. which allows the plugin we are writing to use a standard table of data to search instead of searching multiple tables to look for content. Setting this to 1 will create an up-to-date index of posts, comments, and pages that are in the system which can be searched with a simple query. The sphinx plugin and most database plugins will use the index table so set the value to 1

The new options array for our Sphinx plugin should look like this (with everything enabled):

var $options = array(
            'advanced' => 1,
            'filters' => 1,
            'sort' => 1,
            'pagination' => 1,
            'index' => 1,
        );

After setting the options, we actually need to pass the options array to the Search API. This is done as follows, using the sphinx_search class constructor:

function sphinx_search() {
    $this->parent->options =& $this->options;
}

The next two functions

function search()
{
    global $wpdb;               
}

function find_results()
{
    global $wpdb;
}

contain all the power and functionality of the plugin. The search function is called by the Search API to put together the results and then display them in HTML.

The Sphinx plugin (or another database plugin) will work very much like the MySQL plugin in that we load results in the database using a function called find_results. The Google plugin, on the other hand does not do this, and just leaves the function blank. Both functions should be included.

Note: If you are using the find_results function it should do two things:

$this->results = RESULT_FINDING_METHOD;

// return the total number of results
return TOTAL_NUMBER_OF_RESULTS

Set the results of the search in the $this->results array and then return the total number of results. The total is needed for things such as pagination.

Note: The other code that would go inside these functions is outside of the scope of this article (because it would be discussing more specific items such as loading documents with Sphinx). However the code can be viewed and used in a new plugin under the GPL license.

Finally, unless you have additional methods or functions after find_results(), you need to make sure that you exit out of the class with an ending bracket.

}

Next we have some error checking code to see if another search plugin has already been activated, and if not, the plugin will load itsself.

if( function_exists( "do_search_load" ) ) {
    echo '<div id="message" class="updated fade"><p>';
    _e('You may only have one search plugin using the search api enabled at a time. Please disable the active search plugin first.');
    echo '</p>';
    die;
}
else {  
    function do_search_load() {
        return new sphinx_search();
    }
}

The only thing that you need to worry about here is changing the name of the class in the return new line. Make sure it matches the name of the class we just created.

Next we have some code for when the plugin is activated/installed. The most common functionality is resetting options and refreshing the search index:

register_activation_hook( __FILE__, 'dummy_activate_self' );

function dummy_activate_self() {
//  include_once( "search.php");
//  $index = new search_index();
//  $index->all();
//  delete_option( 'search_custom_options' );
//  delete_option( 'search_help' );

    update_option( 'searchapi_plugin', "search/dummy.php" );
}

Make sure to replace dummy with the name of your plugin (sphinx, mysql, etc) as it needs to be unique for the plugin.

The line 'update_option( 'searchapi_plugin', "search/dummy.php" );' is required for the activate function and should lead to where the plugin is stored assuming we are in the top level plugins directory (ie: for mysql we would use search/mysql.php)

In addition to these running methods the activate_self function can also load help documentation or build an options screen. The below code is from the Google plugin:

global $search_plugin;

    delete_option( 'search_custom_options' );
    delete_option( 'search_help' );

    // This plugin can have a help system for settings
    $help = "<strong>" . __( "Before you can use the Google Search Plugin you must have a Google Custom Search Engine setup with Google." ) . "</strong><br />\n";
    $help .= __( "Follow these steps to sign up for a search engine and/or get the correct settings to enter below:" ) . "<br /><br />\n";
    $help .= "<ol>\n";
        $help .= "<li><a href='http://www.google.com/coop/cse/' target='_blank'>" . __( "Visit the Google Custom Search Site" ) . "</a></li>\n";
        $help .= "<li>" . __( "Either click 'Create a Custom Search Engine' if you need to create one for your site or 'manage your existing search engines' if you have one. You can skip to step 5 if you already have a search engine setup for your site." ) . "</li>\n";
        $help .= "<li>" . __( "Enter a search engine name and description, choose a lanaguage and follow the directions on the first page. Under 'Sites to search:' make sure to enter the full url to your blog. (For example: http://myblog.tld/blog/* to index the entire blog). Click continue." ) . "</li>\n";
        $help .= "<li>" . __( "On the next screen read the information and click the finish button." ) . "</li>\n";
        $help .= "<li>" . __( "Select the search engine you want to configure WordPress for by clicking 'control panel'." ) . "</li>\n";
        $help .= "<li>" . __( "You can edit the settings for the search engine here later but for now click 'Get code' on the left hand side." ) . "</li>\n";
        $help .= "<li>" . __( "Check the middle option 'Host results on my website using an iframe' and some code will be generated." ) . "</li>\n";
        $help .= "<li>" . __( "In the first text box you should see the following line of code: &lt;input type=\"hidden\" name=\"cx\" value=\"SEARCH ID HERE\" /&gt; copy the value that should be in place of 'SEARCH ID HERE'." ) . "</li>\n";
        $help .= "<li>" . __( "Paste the value below and click 'Save Changes'" ) . "</li>\n";
    $hep .= "</ol>\n";

    $search_plugin->build_options( array(
            array( 
                'id' => 'googleid',
                'value' => "",
                'title' => "Google Custom Search ID",
                'desc' => "",
                'required' => 1,
            ),

            array(
                'id' => "charset",
                'value' => "UTF-8",
                'title' => "Google Custom Search Charset",
                'desc' => "",
                'required' => 1,
            )
    ), $help );

Finally, we set all the code in motion by hooking into WordPress using a filter.

add_filter('search_load', 'do_search_load' );
?>

Optionally you can also have a bit of uninstall code within the plugin to delete settings:

if ( function_exists('register_uninstall_hook') )
    register_uninstall_hook(__FILE__, 'PLUGIN_NAME_uninstall');

function PLUGIN_NAME_uninstall() {
    global $wpdb;

    delete_option( 'searchapi_setting );
    // etc
}

Requires: 2.8 or higher
Compatible up to: 2.8.1
Last Updated: 2009-8-25
Downloads: 12,944

Ratings

3 stars
3.3 out of 5 stars

Support

0 of 1 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

0 people say it works.
0 people say it's broken.

100,1,1
50,2,1
33,3,1
20,5,1
0,1,0
17,6,1
0,1,0
50,2,1