Last updated November 12, 2011. Created by danielb on May 30, 2009.
Log in to edit this page.

Finder invokes many possibilities to hook in with a module and change something. This page documents these hooks.

hook_finderapi

hook_finderapi(&$object, $op, $a3 = NULL, $a4 = NULL)

Act upon various Finder operations and make changes to the Finder object.

&$object - The Finder or Finder Element.

$op What kind of action is being performed. Possible values:

* "finder_load": The Finder has been loaded from the database, modules can make changes to the Finder here.
* "finder_presave": The Finder is about to be inserted or updated into the database.
* "finder_insert": The Finder has being created in the database.
* "finder_update": The Finder has being changed in the database.
* "finder_delete": The Finder is being deleted.
* "finder_admin_edit": An admin is about to load the edit page for the Finder.
* "finder_admin_delete": An admin is about to load the delete page for the Finder.
* "finder_element_load": The Finder Element has been loaded from the database, modules can make changes to the Element here.
* "finder_element_presave": The Finder Element is about to be inserted or updated into the database.
* "finder_element_insert": The Finder Element has being created in the database.
* "finder_element_update": The Finder Element has being changed in the database.
* "finder_element_delete": The Finder Element is being deleted.
* "finder_admin_element_edit": An admin is about to load the edit page for the Finder Element.
* "finder_admin_element_delete": An admin is about to load the delete page for the Finder Element.
* "finder_page": The Finder page is being displayed.
* "finder_results": The Finder results are being displayed.
* "finder_block": The Finder block is being displayed.
* "finder_find": The Finder is preparing a query.
* "finder_form": The Finder is preparing a Finder form.
* "finder_admin_list": The Finder is being listed in the admin table.

$a3

* For "finder_results", passes in the $form_state.
* For "finder_find", passes in the $mode string which can be 'choices' (for radio/checkbox/select/autocomplete options) or 'results' (for a submitted search).
* For "finder_form", passes in the $form array.
* For "finder_admin_edit", "finder_admin_delete", "finder_admin_element_edit", and "finder_admin_element_delete", passes in the $form_state

$a4

* For "finder_find", passes in the $finder_element_id useful when $mode is 'choices'.
* For "finder_form", passes in the $form_state array.
* For "finder_admin_element_edit" and "finder_admin_element_delete", passes in the $finder.

Return value

None of the current $ops require a return value.

hook_finder_element_handlers

hook_finder_element_handlers()

Enable new kinds of Element types. Return an array, where the keys are the IDs of the Element Type, and the values are an array where the keys are parameters '#title' and '#module', where the value of '#title' is a translatable string and the value of '#module' is the string name of your module.

Code:

<?php
/**
* Implementation of hook_finder_element_handlers().
*/
function finder_autocomplete_finder_element_handlers() {
  return array(
   
'autocomplete' => array(
     
'#title' => t('Autocomplete textfield'),
     
'#module' => 'finder_autocomplete',
    ),
  );
}
?>

hook_finder_element

hook_finder_element($element, &$form_element)

This function will be called in the module specified in #module for a particular element in hook_finder_element_handlers(). The $element is the Finder Element object, and the $form_element is the Forms API array to manipulate.

Code:

<?php
/**
* Implementation of hook_finder_element().
*/
function finder_text_finder_element($element, &$form_element) {
  if (
$element->element == 'text') {
   
$form_element['#type'] = 'textfield';
   
$properties = array(
     
'field_prefix',
     
'field_suffix',
    );
    if (
$element->settings['form']['rows']) {
     
$form_element['#type'] = 'textarea';
     
$properties[] = 'rows';
     
$properties[] = 'cols';
     
$element->settings['form']['cols'] = $element->settings['form']['size'];
    }
    else {
     
$properties[] = 'maxlength';
     
$properties[] = 'size';
    }
    foreach (
$properties as $property) {
      if (
$element->settings['form'][$property]) {
       
$form_element['#'. $property] = $element->settings['form'][$property];
      }
    }
  }
}
?>

hook_finder_base_handlers

hook_finder_base_handlers()

Enables new types of findable objects in Drupal. Return an array, where the keys are the IDs of the base objects, and the values are an array where the keys are parameters '#title' and '#module', where the value of '#title' is a translatable string and the value of '#module' is the string name of your module.

Code:

<?php
/**
* Implementation of hook_finder_base_handlers().
*/
function finder_node_finder_base_handlers() {
  return array(
   
'node' => array(
     
'#title' => t('Node finder'),
     
'#module' => 'finder_node',
    ),
  );
}
?>

hook_finder_find

hook_finder_find($finder, $finder_element_id, $keywords, $mode, $match, $pager)

This function will be called in the base handler module, it must return an array of results. See finder_node_finder_find() and finder_node_finder_views() for two different approaches to this function. The former uses Finder's internal query engine as well as a helper function it shares with Finder User, the latter loads a View and makes some programmatic changes to fetch the results.

hook_finder_result

hook_finder_result($finder, $keywords, $result_array, $form_state)

This function will be called in the base handler module, it converts the results into themed output, usually through a theme function. See finder_node_finder_result() and finder_views_finder_result() for two different approaches to this function.

hook_form_finder_form_alter

hook_form_finder_form_alter(&$form, &$form_state)

Perform alterations before a Finder form is rendered. This is a good place to add custom FAPI values for #validate, #submit, and #theme.

hook_form_finder_admin_add_form_alter

hook_form_finder_admin_add_form_alter(&$form, &$form_state)

Alter the form on the Finder administration page that lets you add a new Finder. This is usually not necessary.

hook_form_finder_admin_edit_alter

hook_form_finder_admin_edit_alter(&$form, &$form_state, $finder)

Alter the form to configure a Finder, useful for base handler modules to add additional options and validation. Any fields added under $form['settings'] will be automatically saved by Finder and later accessible at $finder->settings

hook_form_finder_admin_delete_alter

hook_form_finder_admin_delete_alter(&$form, &$form_state, $finder)

Alter the Finder delete confirmation form. This is usually not necessary.

hook_form_finder_admin_element_edit_alter

hook_form_finder_admin_element_edit_alter(&$form, &$form_state, $finder, $finder_element_id)

Alter the form to configure a Finder Element, useful for base and element handler modules to add additional options and validation. Any fields added under $form['settings'] will be automatically saved by Finder and later accessible at $element->settings

hook_form_finder_admin_element_delete_alter

hook_form_finder_admin_element_delete_alter(&$form, &$form_state, $finder, $finder_element_id)

Alter the Finder Element delete confirmation form. This is usually not necessary.

hook_finder_find_keywords_alter

hook_finder_find_keywords_alter(&$keywords, $finder, $finder_element_id, $mode, $match, $pager)

Alter the $keywords array used in finder_find().

hook_finder_find_options_alter

hook_finder_find_options_alter(&$options, $finder, $finder_element_id, $keywords, $mode, $match, $pager)

Alter the $options array returned by finder_find().

hook_finder_query_alter

hook_finder_query_alter(&$query)

Alter the query array before finder_query() builds it into SQL.

hook_finder_query_built_alter

hook_finder_query_built_alter(&$query)

Alter the query array before finder_query() executes the SQL.

hook_finder_match_operators_alter

hook_finder_match_operators_alter(&$operators)

Alter the $operators array returned by finder_match_operator().

hook_finder_form_state_alter

hook_finder_form_state_alter(&$form_state, $finder_id)

This is a chance to undo any changes made by the Finder form submit function. If you set $form_state['storage']['finished'] to FALSE here then it will prevent any automatic redirects and allow you to make multistep forms.

hook_finder_goto_alter

hook_finder_goto_alter(&$result, $finder)

This is a chance to do a custom redirect, or to change the $result during a redirect to the first result.

hook_finder_goto

hook_finder_goto($finder, $result)

The base handler module is expected to redirect the user based on the $result by implementing this function.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.