Using Geeklog's Improved Search Engine - Revision history

Sbarakat: /* Including External Results */ Documented callback function

2009-10-25T23:40:36Z

‎Including External Results: Documented callback function

Sbarakat: /* Search by Title */

2009-10-20T21:21:29Z

‎Search by Title

Sbarakat: Documented search by title

2009-10-20T21:20:47Z

Documented search by title

Sbarakat: Added Including External Results

2009-10-20T21:02:56Z

Added Including External Results

Sbarakat: Little shuffling of the sections

2009-10-20T20:14:56Z

Little shuffling of the sections

Sbarakat: /* Identifying A Plugin's Comments */

2009-10-20T20:06:16Z

‎Identifying A Plugin's Comments

Sbarakat: /* Identifying A Plugin's Comments */ Clarified supported GL version

2009-09-30T23:26:54Z

‎Identifying A Plugin's Comments: Clarified supported GL version

Sbarakat: /* Identifying A Plugin's Comments */ Added supported GL version

2009-09-30T23:18:11Z

‎Identifying A Plugin's Comments: Added supported GL version

Sbarakat: /* Standard SQL Query */

2009-09-30T21:14:45Z

‎Standard SQL Query

Sbarakat: /* Returning Multiple Objects */ code typo

2009-09-30T21:09:41Z

‎Returning Multiple Objects: code typo

@@ Line 206: / Line 206: @@
      array(
          array(
-             SQL_NAME => 'myplugin',
+             LF_SOURCE_NAME => 'myplugin',
-             SQL_TITLE => 'My Plugin',
+             LF_SOURCE_TITLE => 'My Plugin',
              'title' => 'Custom Result 1',
              'description' => 'This is a custom result',
@@ Line 216: / Line 216: @@
          ),
          array(
-             SQL_NAME => 'myplugin',
+             LF_SOURCE_NAME => 'myplugin',
-             SQL_TITLE => 'My Plugin',
+             LF_SOURCE_TITLE => 'My Plugin',
              'title' => 'Custom Result 2',
              'description' => 'This is a custom result',
@@ Line 229: / Line 229: @@
 return $search;
 </pre>

@@ Line 132: / Line 132: @@
 <pre>
 $sql = 'SELECT ... FROM ... WHERE ... ';
- $columns = array('title' => 'title','bodytext');
+$columns = array('title' => 'title','bodytext');
 list($sql,$ftsql) = buildSearchSQL('any', 'my geeklog', $columns, $sql);
 </pre>

@@ Line 126: / Line 126: @@
 </pre>
 A proper example of its use is at the bottom of the page.
 ==== Enabling URL Rewrite ====
@@ Line 266: / Line 275: @@
      $search = new SearchCriteria('stories', $LANG09[65]);
-     // These are the columns in the table that need searching
+     // These are the columns in the table that need searching, note we have marked the title column
-     $columns = array('introtext','bodytext','title');
+     $columns = array('title' => 'title','introtext','bodytext');
      // Get back the completed SQL query

@@ Line 182: / Line 182: @@
 // Return both objects
 return array($search_main, $sql_comments);
 </pre>

@@ Line 3: / Line 3: @@
 If you want to make your plugin compatible with Geeklog v1.5 and below, you must also implement [[Using Geeklog's Search Engine]].
-== The functions ==
+== Introduction ==
 Tying your plugin into Geeklog's search API is rather easy.  Easy, that is, if you know how to search your plugin's data already. The Geeklog search API provides a way for you to return the SQL query back to Geeklog which will be executed in the core and the results included in its search page.
-For the data in your plugin to be searched by Geeklog's 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 Geeklog's search engine, 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 search SQL query back to Geeklog.
-Let's look at each of them in turn:
+Over the next few sections we will go over these functions in details.
-=== 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 function will make it all clear.  Normally the function looks like this:
@@ Line 34: / Line 34: @@
 You can have multiple search types and descriptions.
-=== plugin_dopluginsearch_{plugin_name}() ===
+== plugin_dopluginsearch_{plugin_name}() ==
 This section will outline the method used to search a plugin's data.
-==== Input Parameters ====
+=== Input Parameters ===
 The parameters that are passed to this function are as follows:
@@ Line 55: / Line 55: @@
 # Return the query along with some plugin information.
-==== Returned Values ====
+=== Returned Values ===
 The search API requires the following information to be returned by the plugin_dopluginsearch_{plugin_name}() function:
-===== Plugin Name =====
+==== Plugin Name ====
 * A name to display to the user, i.e. 'My Plugin' (singular preferred)
 * A name used locally to identify the plugin, i.e. 'myplugin'
-===== A Search Rank =====
+==== A Search Rank ====
 * An integer between 1 and 5 based on how many result to extract from the query.
@@ Line 77: / Line 77: @@
      comments    2       9
-===== Standard SQL Query =====
+==== Standard SQL Query ====
 * A string containing a single query.
@@ Line 86: / Line 86: @@
 If a column does not exist in the table then another value should be substituted, for example: '0' AS hits, ...
-====== URL ======
+===== URL =====
 The URL is where to take the user when they have clicked a result. It should start with a single slash if the target is within the current domain. Otherwise the result will be printed, as is, in the href attribute of the link. For example this URL belongs to the Geeklog site:
@@ Line 92: / Line 92: @@
 However some plugins may need to direct users to an external site, ie the Links plugin. In this instance providing a full URL will suffice.
-===== Full-Text SQL Query (optional) =====
+==== Full-Text SQL Query (optional) ====
 * An array of two queries for both MSSQL and MySQL DBMS using the Full-Text search method.
@@ Line 98: / Line 98: @@
 This search method will take advantage of Full-Text indexes which are optimised to reduce search times. This should only be returned if the columns being searched have been properly indexed. The Full-Text SQL Query will only be executed if Full-Text searches have been enabled by the admin during the installation or upgrading process, otherwise the core will always fall back to the Standard SQL Query.
-==== The SearchCriteria() Class ====
+=== The SearchCriteria() Class ===
 The process of returning the values is done by initializing a SearchCriteria() object, setting the parameters for the search then returning the object. Here is an example:
@@ Line 107: / Line 107: @@
 This indicates that the 'myplugin' plugin supports Full-Text searches and will have a ranking of 4.
-===== buildSearchSQL() Function =====
+==== buildSearchSQL() Function ====
 As a lot of the plugins will be processing the same or similar SQL queries the buildSearchSQL() function has been provided to simplify things. This function will take four parameters then build the searching part of the SQL query. It will also return the Full-Text query strings should they be required. The parameters are:
@@ Line 127: / Line 127: @@
 A proper example of its use is at the bottom of the page.
-===== Enabling URL Rewrite =====
+==== Enabling URL Rewrite ====
 If the plugin requires the URL to be passed through the COM_buildUrl() function then it should set the setURLRewrite() function to true. For example:
@@ Line 134: / Line 134: @@
 $search->setURLRewrite(true);</pre>
-===== Returning Multiple Objects =====
+==== Returning Multiple Objects ====
 In some cases a plugin may be required to search across two or more tables that have no relation with one another. To accommodate this they may return an array of SearchCriteria() objects, each with a different SQL query. To allow the user to differentiate between the results an array of names can be passed, each name will be a separate sub group and will be appended to one another using the separator from the configuration.
@@ Line 159: / Line 159: @@
 Note: The plugin identifier needs to stay the same across all objects, in this case 'myplugin'.
-===== Identifying A Plugin's Comments =====
+==== Identifying A Plugin's Comments ====
 Some plugins may have comments associated with them such as the [[File Management Plugin|FileMgmt]] or Static Pages. To allow these comments to be searched the core needs to know where to find them. The process is similar to [[#Returning Multiple Objects|returning multiple SearchCriteria() objects]] with the exception of identifying the object that contains the comments. This is done by setting the plugin name to 'comments'. As comments will be included in general searches it is best practice to set a lower rank for the comments object to ensure the search results page isn't spammed with comment results.
@@ Line 184: / Line 184: @@
 </pre>
-==== A Working Example ====
+== A Working Example ==
 This example searches the Stories. Although it's not a plugin, it puts to use everything discussed here so it's a good example of how to implement the API in your plugin.

@@ Line 161: / Line 161: @@
 ===== Identifying A Plugin's Comments =====
-Some plugins may have comments associated with them such as the [[File Management Plugin|FileMgmt]] or the Polls Plugin. To allow these comments to be searched the core needs to know where to find them. The process is similar to [[#Returning Multiple Objects|returning multiple SearchCriteria() objects]] with the exception of identifying the object that contains the comments. This is done by setting the setComment() function to true. As comments will be included in general searches it is best practice to set a lower rank for the comments object to ensure the search results page isn't spammed with comment results.
+Some plugins may have comments associated with them such as the [[File Management Plugin|FileMgmt]] or Static Pages. To allow these comments to be searched the core needs to know where to find them. The process is similar to [[#Returning Multiple Objects|returning multiple SearchCriteria() objects]] with the exception of identifying the object that contains the comments. This is done by setting the plugin name to 'comments'. As comments will be included in general searches it is best practice to set a lower rank for the comments object to ensure the search results page isn't spammed with comment results.
-Using separate objects is the prefered method of separating a plugins comments from the main results. The setComment() function however is only available as of ''Geeklog 1.6.1''. To lower the plugin's requirements to 1.6.0 it would be best to check the function exists before executing it.
+Using separate objects is the prefered method of separating a plugins comments from the main results. This method of searching for comments was introduced in ''Geeklog 1.6.1''.
 Below is a short example.
@@ Line 176: / Line 176: @@
 // Search the comments tables
 $sql_comments = "SELECT ... FROM gl_comments" WHERE ...";
-$search_comments = new SearchCriteria('myplugin', array('My Plugin', 'Comments'));
+$search_comments = new SearchCriteria('comments', array('My Plugin', 'Comments'));
 $search_comments->setSQL($sql_comments);
 $search_comments->setRank(1);
@@ Line 184: / Line 183: @@
 return array($search_main, $sql_comments);
 </pre>
 ==== A Working Example ====

← Older revision		Revision as of 23:18, 30 September 2009
Line 160:		Line 160:

	===== Identifying A Plugin's Comments =====		===== Identifying A Plugin's Comments =====
		+
		+	''This feature is available as of Geeklog 1.6.1''

	Some plugins may have comments associated with them such as the [[File Management Plugin\|FileMgmt]] or the Polls Plugin. To allow these comments to be searched the core needs to know where to find them. The process is similar to [[#Returning Multiple Objects\|returning multiple SearchCriteria() objects]] with the exception of identifying the object that contains the comments. This is done by setting the setComment() function to true. As comments will be included in general searches it is best practice to set a lower rank for the comments object to ensure the search results page isn't spammed with comment results.		Some plugins may have comments associated with them such as the [[File Management Plugin\|FileMgmt]] or the Polls Plugin. To allow these comments to be searched the core needs to know where to find them. The process is similar to [[#Returning Multiple Objects\|returning multiple SearchCriteria() objects]] with the exception of identifying the object that contains the comments. This is done by setting the setComment() function to true. As comments will be included in general searches it is best practice to set a lower rank for the comments object to ensure the search results page isn't spammed with comment results.

@@ Line 83: / Line 83: @@
 All SQL queries returned should be without the LIMIT and ORDER BY clauses. The SQL query must have the following column names and look like:
-<pre>SELECT id, title, description, date, uid, hits, url FROM ... WHERE ...{space}</pre>
+<pre>SELECT id, title, description, date, uid, hits, url FROM ... WHERE ...</pre>
 If a column does not exist in the table then another value should be substituted, for example: '0' AS hits, ...

@@ Line 143: / Line 143: @@
 //   These results will be labelled 'My Plugin > Main'
 $search_main = new SearchCriteria('myplugin', array('My Plugin', 'Main'));
-$plugin_main->setSQL($sql_main);
+$search_main->setSQL($sql_main);
-$plugin_main->setFTSQL($ftsql_main);
+$search_main->setFTSQL($ftsql_main);
-$plugin_main->setRank(4);
+$search_main->setRank(4);
 // Search a sub tables