CiviCRM Entity - Using Drupal Search and Facet APIs with CiviCRM Data

There are two powerful modules used in the Drupal world for creating fast custom searches. Search API is a framework which provides an interface for site builders to create custom searches on any entity known to Drupal. It supports several search backends, including Apache Solr and native database search. It has a flexible API so developers can easily extend, customize, and alter aspects of the search process. Many additional contrib modules are available. Using these techniques, searching millions of records becomes fast and efficient.

The Facet API module allows site builders to easily create and manage faceted search interfaces. In addition to the UI components that standard, themers and module developers can build their own widgets, or alter the out-of-the-box widgets.

This one-two punch of powerful modules brings extremely powerful, flexible, and as you will see, easy to use custom search functionality to Drupal. Oftentimes all that is required is configuration through the admin interface, although the development API is extensive and the imagination is the limit for what can be done.

Creating custom searches for CiviCRM has always been a developer task, and the facilities are limited from both a site builder and a developer perspective. Wouldn't it be great to use Drupal's powerful search modules with CiviCRM data? Well folks, you can, with a little help from CiviCRM Entity.

CiviCRM Entity is a Drupal module which exposes many CiviCRM entities as true Drupal entities. That means that almost any module that can use Drupal entities, can access and manipulate CiviCRM data, Drupal style. This includes many commonly used modules such as Views, Rules, Entity Reference, Entityqueue, and many more.

There is a sub module that ships with CiviCRM Entity, called CiviCRM Entity Search API.  This supports advanced index update operations for Contacts and Memberships currently, and more will be added in the future.

Create a Custom Search and Display

In this article I'll outline the basic instructions and methods that can be used create custom searches on nearly 20 different CiviCRM entities. As an example, we'll build a custom Contact search, with a faceted block interface for Contact Type. This is the simplest example of what can be done. There are tons of options and configurations -- too many to outline fully in one blog article.

We'll be using native database search indexing in this article, but this methods applies to Apache Solr as well as several other available backend service classes.

The interface for the search will be created using blocks and a view, which will integrate into your theme. If your theme is responsive, then your custom search will be, too!

Step-by-Step

The full step by step instructions are detailed on Skvare's blog.

1. Install and Configure System Requirements
2. Create Search Server Instance
3. Create a Contact Search Index Instance
4. Select Fields to Index
5. Configure Filters
6. Facets
7. Index the Contacts
8. Create the Search View
9. Configure View fields and Filters
10. Contact Type Facet Block
11. The Results

Conclusion

You can have multiple facets per view, and using one of the many contrib modules that extend these modules, there is hardly a limit to what you can achieve. All of this can be achieved with zero additional code, pure site building. There is a strong developer api for customizing and extending this functionality even further.

Also, there are no CiviCRM permissions stopping users from visiting the view. You can control permissions with standard Views permissions. If you want to expose CiviCRM data to users, but not give those users any permission to access the CiviCRM backend, then it can be so. If your theme is responsive, then your search view can be, too.

This is a very simple example of what is possible, and I hope you can see the vast potential involved with these modules and techniques. Really the limit is your imagination.

Have fun building your own specific implementations!

Skvare is a leader in Drupal and CiviCRM integration. Contact us to get questions answered and for consultations to make the most of your Drupal and CiviCRM installation.

/**
 * Implements hook_facet_items_alter().
 */
function YOUR_MODULE_NAME_facet_items_alter(&$build, &$settings) {
  // name of your facet goes below, use dsm($settings) to discover
  if ($settings->facet == "gender_id") {
    if (!civicrm_initialize()){
      return;
    }
    $result = civicrm_api3('Contact', 'getoptions', array(
      'sequential' => 1,
      'field' => "gender_id",
    ));
    $genders = array();
    if (!$result['is_error'] && count($result['values'])){
      foreach ($result['values'] as $gender){
        $genders[$gender['key']] = $gender['value'];
      }
    }
    foreach ($build as $key => $item) {
      if (isset($genders[$key])) {
        $build[$key]["#markup"] = $genders[$key];
      }
      elseif ($key == 0) {
        $build[$key]["#markup"] = 'Not specified';
      }
    }
  }
}