Using the OSF SearchAPI Module

From OSF Wiki
Jump to: navigation, search


Screencast Tutorial


The Drupal SearchAPI is a module that is used to create a search engine for a Drupal website. OSF for Drupal does re-implement the general SearchAPI to be able to communicate with the Search web service endpoint.

Note: it is assumed that you installed OSF for Drupal with the OSF Installer script. This means that the SearchAPI server and index are already configured in your instance. If not, then you will have to create them by hands.

Configuring the Search Engine Server

The first step is to configure the search engine. Even if we consider that the search server is already configured, we will see what are these configurations and how they can eventually be modified.

To access the configuration pages of the search engine, you have to click on the top Configuration menu item. Then you have to search an click on the Search API link.

Searchapi access.PNG

Then you will get to the list of all the configure SearchAPI Servers and Indexes. If you installed OSF for Drupal using the OSF Installer tool, then you should see appearing the OSF Search server and the OSF Search Index index.

Note: If you have to configure them by hands, it is essential that the name of the Server is OSF Search and the name of the index is OSF Search Index. That way, the machine names for this server and this index will be properly generated and usable by the OSF SearchAPI module.

Searchapi servers indexes list.PNG

First, let's edit the OSF Search server by clicking the edit link for that line item.

Searchapi edit server.png

There is one major feature other than the server's name: the OSF Service's endpoint. In the Network options list, you have the list of all the registered OSF Web Services endpoints on that Drupal instance. What you have to do is to select the one you want to use where to send the Search queries.

Once you selected the OSF Web Services endpoint to use, you only have to click Save settings.

Searchapi editing server.PNG

Configuring the Search Page

Once the search server is properly configured, the next step is to configure the search page. The search page is the URL where the search engine will be accessible to the users. By going to that URL, the users will be able to use the search engine we are configuring.

To access the search pages, you have to click the Search Pages tab when you are looking at the list of available servers and indexes.

Searchapi edit search pages.png

This will redirect you to the list of available search pages. If you installed OSF for Drupal using the OSF Installer tool, you should see a search page that has lookup as the path. Then if we want to edit that path, we have to click the edit link.

Searchapi search pages list.PNG

The setting we are interested in in this page is the Path. The path is the URL path where the search engine page will be accessible. If the search page is configured like this, it means that the search engine page will be available to the users that goes to this URL:

Searchapi edit search page.PNG

Configuring Search Facets

Once the search server and the search page are properly configured, one thing that the administrators may want to do is to configure a series of search facets blocks that would be available to the users to facet the information they are searching for.

To configure the facets, you have to click the edit link for the index. Then click the Facets link that will appear.

Searchapi edit index.png

You will then get redirected to the page that list all the available facets to the users (there can be quite a few). All the properties that are used in any available dataset may become a facet in the search engine. In this example, we selected the district and the Dataset facets.

Once you selected all the facets you want to expose, you have to click the Save configuration button.

What happen when you click that button is that a Block will be created for each facet you selected.

Searchapi index facets.PNG

The next step is to configure the facet blocks that you created by selecting the facets to expose. What you have to do is to go to the list of all blocks, and then search for the Facet API: Search service: OSF Search Index: Facet-ABC blocks. These are the blocks that have been created by the previous step. All the facets will be displayed in these blocks.

Searchapi facet blocks.PNG

By default, these blocks are disabled. The next step is to position the blocks in the layout of your theme. Once you positioned them, you have to click to save the configuration of the blocks before configuring the blocks individually.

Searchapi facet blocks positioning.PNG

The last step is to configure the blocks. Beside the positioning of the blocks, the main configuration options for these facets blocks are the visibility settings. There are the settings you will be using to determine where (which page) and who will have access to these facets blocks.

Searchapi facet block configuration.PNG

Using the Search Engine

Once everything is properly configured, you can go to the lookup page to start searching for content that comes from your OSF instance. There are three major areas in a search page:

  1. Search box
  2. Search results
  3. Search facets

If you enter a search keyword in the search box, then all the results will appear below that search box and the facets blocks will appears where they got positioned. Each of the facets that have been exposed will be populated with a series of values that could be used to filter the content of the search resultset. The number of records in each facet is displayed in parenthesis.

It is also possible to theme the results that are returned. Check the Theming OSF SearchAPI results section for more information.

Searchapi search.PNG

If you click on one of the facet, you will be redirected to a new search page where the facet as been applied. The number of results should go down after the facet is applied to the search query. More than one facet can be applied to a single search query. Search facets can be removed by clicking the (-) link.

Searchapi search with facet.PNG