Difference between revisions of "Using Geeklog's Search Engine"

Revision as of 07:46, 9 May 2009

Note: The information on this page refers to the old search API which makes use of the Plugin() class. There has since been improvements made to the search pages that requires an updated API which makes use of the new and improved SearchCriteria() class.

Tying your plugin into Geeklogs search API is rather easy. Easy, that is, if you know how search your plugins data already. The Geeklog search API provides a way for you to return your search results back to Geeklog to be included in its search results page.

For the data in your plugin to be searched by Geeklogs search functions, there are two functions that you need to implement in your plugins function.inc:

• plugin_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
• plugin_dopluginsearch_{plugin_name}() returns the actual results to Geeklog.

Let's look at each of them in turn:

plugin_searchtypes_{plugin_name}()

This function takes no parameters and returns an associative array of the search type. The normal code for this function will make it all clear. Normally the function looks like this:

function plugin_searchtypes_{plugin_name}() {
    global $LANG_PL00;
    $tmp['searchtype']= $LANG_PL00['searchtype'];
    return $tmp;
}

Naturally all occurrences of plugin would be replaced with the name of your plugin and the LANGUAGE varible $LANG_PL00 is just an example. Your Plugin needs to use a unique variable name so replace PL00.

The return array is of the format array['searchtype'] = 'Search Description', where searchtype is returned to your plugin search routine and Description is displayed in the Search Page Drop Down box.

You can have multiple search types and descriptions.

plugin_dopluginsearch_{plugin_name}()

This function is where the search is actually done. It is passed a number of parameters that can be used in your search. They are:

• $query -- the actual items being searched for.
• $datestart -- starting date to begin search.
• $dateend -- ending date to end search.
• $topic -- topic item is assigned to.
• $type -- type of item (see searchtypes above).
• $author -- author of item.

Depending on your plugin, some of these criteria may be meaningless and thus ignored. Here is a brief overview of what your function should do.

1. Initialize plugin object
2. Check to see if type is appropriate for this plugin -- if not, bail out.
3. Get a list of all your items to search.
4. Create Search object and Build search results header.
5. Search each of your items in turn.
6. If a match then add item to the results.
7. When done set number of results and return search object

Looking at the example code should make all of this clear. The search results are returned in a object of type Plugin. You initialize the object by setting the Label and then setting the names of the columns you want returned. This is done in typical object fashion with this construct: $plugin->addSearch Heading.

The headings will vary according to what your plugin does, but should include a link to the item found. After searching each of your items in turn; you add your search results to an array having the same number of items as the labels you set earlier.

Note: your search should be case insensitive to be compatible with Geeklogs search. This array will correspond to the column headings entered above. In the example below, the array consists of the Title of the page, the url to the page (a link) and the number of hits. This array is then added to the Plugin object as a row.

The following construct is used: $plugin->addSearchResult. When you are done searching you set the number of rows found and the number searched to the plugin object and return it. The example below is from the External Pages Plugin.

function plugin_dopluginsearch_external($query,$datestart,$dateend,$topic,$type,$author)
{
    global $_TABLES, $_CONF, $LANG_EX00;

    if (empty($type)) {
        $type = 'all';
    }
      
    // Bail if we aren't supppose to do our search
    if ($type <> 'all' AND $type <> 'external') {
        $plugin_results = new Plugin();
        $plugin_results->plugin_name = 'external';
        $plugin_results->searchlabel = $LANG_EX00['externpages'] . $LANG_EX00['results'];
        return $plugin_results;
    }
      
    // Build search SQL - Modified to exclude static PHP pages from search.
    $sql = "SELECT * from " . $_TABLES['external'];
    $result = DB_query($sql);
    
    // OK, now create new plugin object and insert table header labels
    require_once($_CONF['path_system'] . 'classes/plugin.class.php');
    $plugin_results = new Plugin();
    $plugin_results->plugin_name = 'external';
    $plugin_results->searchlabel = $LANG_EX00['externpages'] . $LANG_EX00['results'];
    $plugin_results->addSearchHeading($LANG_EX00['titlemsg']);
    $plugin_results->addSearchHeading($LANG_EX00['urlmsg']);
    $plugin_results->addSearchHeading($LANG_EX00['hitsmsg']);
    $mycount = DB_numRows($result);
    // NOTE if any of your data items need to be links then add them here! 
    // make sure data elements are in an array and in the same order as your
    // headings above!
    for ($i = 1; $i <= $mycount; $i++) {
        $A = DB_fetchArray($result);

        if(SEC_hasAccess($A[owner_id],$A[group_id],$A[perm_owner],$A[perm_group],$A[perm_members],$A[perm_anon])){
            if (preg_match("/^(http:\/\/)/i",$A['url']) == 1) {
                $pth = $A['url'];
                $url = $A['url'];
            } else {
                $pth = $_CONF['path_html'] . $A['url'];
                $url = $_CONF['site_url'] . '/' . $A['url'];
            }
            $cnts = implode('',file($pth));
            if (stristr($cnts,$query) != '') {
                $rcnt++;
                $A['title'] = stripslashes($A['title']);
                $row = array($A['title'],
                      '<a href="' . $url . '">' . $A['url'] . "</a>",
                     $A['hits']);
                $plugin_results->addSearchResult($row);
            }
        }
    
    }
    $plugin_results->num_searchresults = $rcnt;
    $plugin_results->num_itemssearched = DB_count($_TABLES['external']);

    return $plugin_results;
}