finder_find

Versions
6--1: finder_find($finder, $keywords, $mode = 'choices', $match = 'e', $pager = 0, $finder_element_id = NULL, $reset = FALSE)

Get a list of choices for form or results.

This will invoke the base handler module's hook_finder_find() implementation. It also allows for hooks to alter the keywords, finder, and choices/results.

see hook_finder_find()

Parameters

$finder The finder object.

$keywords An array keyed by finder_element_id, where the values are any str/num/bool/null or an array of such values to be OR'd together.

$mode 'choices' or 'results' depending on what we are fetching.

$match The match method, see finder_match_operator().

$pager Used to limit choices or results per page.

$finder_element_id If $mode is 'choices', this is the finder element id to get choices for.

$reset Reset the cached return value for this set of parameters.

Return value

An array of choices/results.

▸ 3 functions call finder_find()

▾ 3 functions call finder_find()

finder_autocomplete_autocomplete in modules/finder_autocomplete/finder_autocomplete.module: Menu callback; get autocomplete suggestions.
finder_optionwidgets_finder_element in modules/finder_optionwidgets/finder_optionwidgets.module: Implementation of hook_finder_element().
finder_results in ./finder.module: Create finder results output.

Code

./finder.module, line 783

<?php
function finder_find($finder, $keywords, $mode = 'choices', $match = 'e', $pager = 0, $finder_element_id = NULL, $reset = FALSE) {
  static $finder_find_cache = array();

  // For a 'choices' find we need a main element to focus our query around
  // normally calling finder_find() you would not specify the $finder_element_id
  // but it would be interpreted as the index of the last $keywords element
  // though some modules may need to specify a main element other than the last
  // so that parameter is available.  This value is best left 'NULL' for 'results'.
  if ($mode == 'choices' && is_null($finder_element_id)) {
    // no $finder_element_id was passed as the current element we're doing
    // so let's assume the last array key in $keywords is current finder_element_id
    $finder_element_id = end(array_keys($keywords));
  }

  // Create an ID using the function params so we can cache the return value.
  $id = ($mode == 'choices' ? 'e'. $finder_element_id : 'f'. $finder->finder_id) .'|';
  $id_length = strlen($id);
  $cache_id = ($match != 'e' ? $match : '') 
            . ($pager ? $pager : '')
            . serialize($keywords);
  $cache_id_length = strlen($cache_id);
  if (($cache_id_length + $id_length) > 255) {
    // For ID's that (will) exceed 255 we will try to represent them a unique way and pray for the best :/
    $cache_id = md5($cache_id) 
              . $cache_id_length 
              . substr($cache_id, 0, 223 - strlen($cache_id_length) - $id_length);  // 223 = 255 - 32
  }
  $cache_id = $id . $cache_id;

  if (isset($finder_find_cache[$cache_id])) {
    // Use the static data.
    $options = $finder_find_cache[$cache_id];
  }
  else if ($finder->settings['advanced']['cache_finder_find'] 
    && !$reset 
    && ($cache = cache_get($cache_id, 'cache_finder_find')) 
    && !empty($cache->data)) {
    // Use the cached data.
    $options = $cache->data;
  }
  else {
    // Calculate the values from the database.
    
    // Figure out which module is the base module (the module that tells us the options)
    $module = &$finder->base_handler['#module'];

    // Allow other modules to intefere with the keywords.   
    drupal_alter('finder_find_keywords', $keywords, $finder, $finder_element_id, $mode, $match, $pager);

    // Allow other modules to react to and alter the finder.
    finder_invoke_finderapi($finder, 'finder_find', $mode, $finder_element_id);
/*
    // Get the options from the base module.
    if ($mode == 'results' && $finder->settings['advanced']['combination_method']) {
      // This is the implementation of the 'program' combination method.
      if (!$finder->settings['advanced']['element_combination']) {
        // In this case we need all the results
        $element_pager = 0;
      }
      else {
        $element_pager = $pager;
      }
      foreach ($keywords as $keyword_feid => $keyword_data) {
        $element_keywords = array($keyword_feid => $keyword_data);
        $element_options = module_invoke($module, 'finder_find', $finder, $keyword_feid, $element_keywords, 'choices', $match, $pager);
        if ($finder->settings['advanced']['element_combination']) {
          // match 'any' element - just add the results to options
          $options = $options + $element_options;
        }
        else {
          // match 'all' elements - add to $options if empty, if not empty intersect with $options
          $options = isset($options) ? array_unintersect($options, $element_options, $module .'_finder_intersect_results') : $element_options;
        }
      }

      // to do - if !element_combination truncate list to pager size and offset by pager page :/
    }
    else {
      */
      $options = module_invoke($module, 'finder_find', $finder, $finder_element_id, $keywords, $mode, $match, $pager);

      // If mode is choices, we want to conduct some extra processing on this list.
      if ($mode == 'choices') {
        $options = finder_find_choices($finder, $finder_element_id, $options, $keywords[$finder_element_id], $match);
      }
/*
    }
*/

    // Allow other modules to intefere with the options.
    drupal_alter('finder_find_options', $options, $finder, $finder_element_id, $keywords, $mode, $match, $pager);

    // Add the resulting $options to the drupal cache.
    if ($finder->settings['advanced']['cache_finder_find']) {
      cache_set($cache_id, $options, 'cache_finder_find', time() + $finder->settings['advanced']['cache_finder_find']);
    }

    // Add the resulting $options to the static internal load cache.
    $finder_find_cache[$cache_id] = $options;

  }

  return $options;
}
?>

Search Finder API Reference