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

From GeeklogWiki
Jump to: navigation, search
(Placed new API at the top)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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 [[Using Geeklog's Improved Search Engine|SearchCriteria()]] class.
+
== New Search API (GL v1.6.x or greater) ==
 +
As of Geeklog v1.6 the core search functionality has been changed which has required updated API methods. The new API makes use of the new and improved '''SearchCriteria()''' class. See [[Using Geeklog's Improved Search Engine]].
  
 +
== Old Search API (GL v1.5.x or below) ==
 +
The methods documented on this page are meant for Geeklog v1.5 and below. They make use of the Plugin() class which will eventually be phased out.
  
 
+
===The functions===
 
+
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.
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:
 
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_searchtypes_{plugin_name}() returns to Geeklog the type(s) of search.
*plugin_dopluginsearch_{plugin_name}() returns the actual results to Geeklog.
+
* plugin_dopluginsearch_{plugin_name}() returns the actual results to Geeklog.
  
 
Let's look at each of them in turn:
 
Let's look at each of them in turn:
  
 
+
==== plugin_searchtypes_{plugin_name}() ====
== plugin_searchtypes_{plugin_name}() ==
 
 
 
  
 
This function takes no parameters and returns an associative array of the search type.  The normal code for this
 
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 will make it all clear.  Normally the function looks like this:
  
 +
<pre>
 
function plugin_searchtypes_{plugin_name}() {
 
function plugin_searchtypes_{plugin_name}() {
 
     global $LANG_PL00;
 
     global $LANG_PL00;
     $tmp['searchtype']= $LANG_PL00['searchtype'];
+
     $tmp['{plugin_name}']= $LANG_PL00['searchtype'];
 
     return $tmp;
 
     return $tmp;
 
}
 
}
 +
</pre>
 +
<sup>(don't forget to replace {plugin_name} with the actual name).</sup>
  
Naturally all occurrences of plugin would be replaced with the name of your  
+
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.
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  
+
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.
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.
 
You can have multiple search types and descriptions.
  
 +
==== plugin_dopluginsearch_{plugin_name}() ====
  
== 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.
This function is where the search is actually done.  It is passed a number of parameters that can be used
+
* $datestart -- starting date to begin search.
in your search.  They are:
+
* $dateend -- ending date to end search.
 
+
* $topic -- topic item is assigned to.
*$query -- the actual items being searched for.
+
* $type -- type of item (see searchtypes above).
*$datestart -- starting date to begin search.
+
* $author -- author of item.
*$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.
 
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.
  
#Initialize plugin object
+
# Initialize plugin object
#Check to see if type is appropriate for this plugin -- if not, bail out.
+
# Check to see if type is appropriate for this plugin -- if not, bail out.
#Get a list of all your items to search.
+
# Get a list of all your items to search.
#Create Search object and Build search results header.
+
# Create Search object and Build search results header.
#Search each of your items in turn.
+
# Search each of your items in turn.
#If a match then add item to the results.
+
# If a match then add item to the results.
#When done set number of results and return search object
+
# 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  
+
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 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  
+
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.     
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
+
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 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.  
 
The following construct is used:  $plugin->addSearchResult.  
When you are done searching you set the number of rows found and the number  
+
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.
searched to the plugin object and return it.
+
 
The example below is the External Pages Plugin.
+
<pre>
 +
function plugin_dopluginsearch_external($query,$datestart,$dateend,$topic,$type,$author)
 +
{
 +
    global $_TABLES, $_CONF, $LANG_EX00;
  
function plugin_dopluginsearch_external($query,$datestart,$dateend,$topic,$type,$author){
 
    global $_TABLES, $_CONF,$LANG_EX00;
 
 
     if (empty($type)) {
 
     if (empty($type)) {
 
         $type = 'all';
 
         $type = 'all';
Line 136: Line 126:
 
     return $plugin_results;
 
     return $plugin_results;
 
}
 
}
 +
</pre>
  
[[Category:Plugin Development]]
+
[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Latest revision as of 21:40, 20 October 2009

New Search API (GL v1.6.x or greater)

As of Geeklog v1.6 the core search functionality has been changed which has required updated API methods. The new API makes use of the new and improved SearchCriteria() class. See Using Geeklog's Improved Search Engine.

Old Search API (GL v1.5.x or below)

The methods documented on this page are meant for Geeklog v1.5 and below. They make use of the Plugin() class which will eventually be phased out.

The functions

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['{plugin_name}']= $LANG_PL00['searchtype'];
    return $tmp;
}

(don't forget to replace {plugin_name} with the actual name).

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;
}