Creating a Smart Search plug-in

From Joomla! Documentation

This page contains changes which are not marked for translation.
Other languages:
Deutsch • ‎English • ‎中文(台灣)‎

Smart Search Plugins are gathered together for convenience into a Plugin group called "finder". Take a look in the plugins/finder directory and you will see the Plugins that support the core Joomla content types. It is best to create your own Plugin by taking a copy of one of these Plugins and adapting it to meet your needs.

All Smart Search Plugins extend the FinderIndexerAdapter class which contains many methods to deal with maintaining the index. For most of custom content requirements you only need to override a few of these methods.

There is some additional information on writing a Smart Search Plugin.

The Principal Properties[edit]

Before looking at the methods, there are a few properties that need to be set up correctly:

  • $context
    This should be a unique identifier for the Plugin and establishes the context that the Plugin will respond to (e.g. "Content").
  • $extension
    The name of the extension (component) that handles the content type (e.g. "com_content").
  • $layout
    The sublayout to use when rendering search results. For example, of $layout is set to "article" then the default view will look for a layout file called default_article.php when it needs to render a search result of this type. If no such file is found then the layout file called default_result.php will be used instead.
  • $table
    The name of the table to retrieve data from (e.g. "#__content").
  • $state_field
    The database field in your table that the published state of an item is stored in. Defaults to "state".

The Principal Methods[edit]

The first methods you will want to override when developing a new Smart Search Plugin are the setup, index and getListQuery methods. In the majority of cases those three methods will be enough to get your content indexed, although the Plugin will not be complete as there are other methods that must be implemented to deal with issues such as updating the index when the content changes. But those three methods are the working core of the Plugin.

  • setup
    This method is called by the indexer once before an indexing run begins. It can be used to load libraries or initialise variables for the Plugin. Must return true.
  • index
    This is the main method called by the indexer. It is called once for each content item that is to be indexed (or the index updated). The index method essentially describes the content to the indexer by telling the indexer which fields to parse for terms/phrases and their relative weights, which fields to map into branches of the content map and what data to include in the index as "payload". This method is described in more detail later.
  • getListQuery
    This method must return a JDatabaseQuery object that will form the basis of a query that will return a list of objects of the given content type. There are constraints on this query to ensure that it is compatible with other methods used by the indexer. This method is described in more detail later.

Some Other Methods[edit]

For a complete Smart Search Plugin there are other methods you may need to override.

  • translateState
    Given a content item this method translates the native state of the content item into a state that the indexer can use. It must return an integer 0 if the content item is not to appear in search results, or an integer 1 if the content item can appear in search results.
  • getURL
    Returns the non-SEF URL for an item. The default return, using plg_finder_content for example, is index.php?option=com_content&view=article&id=1.
  • getStateQuery
    This method is used to build a generic query for checking the access and state of items and their parent categories. This method uses the $table and $state_field properties to select the correct data.

Event Methods[edit]

The following methods are called via the Smart Search content Plugin in response to specific trigger events in Joomla.

  • onFinderBeforeSave
    Called in response to an onContentBeforeSave event.
  • onFinderAfterSave
    Called in response to an onContentAfterSave event.
  • onFinderAfterDelete
    Called in response to an onContentDelete event.
  • onFinderChangeState
    Called in response to an onContentChangeState event.
  • onFinderCategoryChangeState
    Called in response to an onCategoryChangeState event.

Methods in More Detail[edit]

getListQuery[edit]

This method must return a JDatabaseQuery object that will form the basis of a query that will return a list of objects of the given content type. There are constraints on this query to ensure that it is compatible with other methods used by the indexer. If the following conditions are not true you will need to override other methods in the FinderIndexerAdapter class.

  • The primary database table that is being indexed must have an alias of "a".[1]

Index[edit]

This method is called whenever a content item needs to be indexed (or re-indexed). It is passed an object of type FinderIndexerResult and its purpose is to make adjustments to that object and to add metadata before handing control to FinderIndexer::index method to do the indexing proper.

Setup[edit]

This method is called prior to the index method and is used to set up the index process. This method is where you would typically include any externally-required classes to allow for proper indexing.

FinderIndexerResult Properties[edit]

  • url
  • route
  • title
  • description
  • published
  • state
  • access
  • language
  • publish_start_date
  • publish_end_date
  • extension (only used in core for com_categories plugin)

Testing[edit]

Testing a finder plugin can be difficult due to the fact that it is typically run using an Ajax process, so you don't tend to actually see any results from the process.

As such, one way to test is to use the command line indexer.[2]

Open a command prompt/SSH session on the server and go to the root directory of the website. From there, you can run the indexer and errors and log messages will go to the screen. php cli/finder_indexer.php

Notes[edit]

  1. If this condition is not true you will also have to override the getItem, getUpdateQueryByTime and getUpdateQueryByIds methods
  2. Setting up automatic Smart Search Indexing