function ctools_plugin_api_info in Chaos Tool Suite (ctools) 6

Same name and namespace in other branches

1. 7 includes/plugins.inc \ctools_plugin_api_info()

Get an array of information about modules that support an API.

This will ask each module if they support the given API, and if they do it will return an array of information about the modules that do.

This function invokes hook_ctools_api. This invocation is statically cached, so feel free to call it as often per page run as you like, it will cost very little.

This function can be used as an alternative to module_implements and can thus be used to find a precise list of modules that not only support a given hook (aka 'api') but also restrict to only modules that use the given version. This will allow multiple modules moving at different paces to still be able to work together and, in the event of a mismatch, either fall back to older behaviors or simply cease loading, which is still better than a crash.

Parameters

$owner: The name of the module that controls the API.

$api: The name of the api. The api name forms the file name: $module.$api.inc

$minimum_version: The lowest version API that is compatible with this one. If a module reports its API as older than this, its files will not be loaded. This should never change during operation.

$current_version: The current version of the api. If a module reports its minimum API as higher than this, its files will not be loaded. This should never change during operation.

Return value

An array of API information, keyed by module. Each module's information will contain:

• 'version': The version of the API required by the module. The module should use the lowest number it can support so that the widest range of supported versions can be used.
• 'path': If not provided, this will be the module's path. This is where the module will store any subsidiary files. This differs from plugin paths which are figured separately.

APIs can request any other information to be placed here that they might need. This should be in the documentation for that particular API.

1 call to ctools_plugin_api_info()

ctools_plugin_api_include in includes/plugins.inc

Load a group of API files.

1 string reference to 'ctools_plugin_api_info'

ctools_get_plugins_reset in includes/plugins.inc

Reset all static caches that affect the result of ctools_get_plugins().

File

includes/plugins.inc, line 57

Contains routines to organize and load plugins. It allows a special variation of the hook system so that plugins can be kept in separate .inc files, and can be either loaded all at once or loaded only when necessary.

Code

function ctools_plugin_api_info($owner, $api, $minimum_version, $current_version) {
  $cache =& ctools_static(__FUNCTION__, array());
  if (!isset($cache[$owner][$api])) {
    $cache[$owner][$api] = array();
    foreach (module_implements('ctools_plugin_api') as $module) {
      $function = $module . '_ctools_plugin_api';
      $info = $function($owner, $api);
      if (!isset($info['version'])) {
        continue;
      }

      // Only process if version is between minimum and current, inclusive.
      if ($info['version'] >= $minimum_version && $info['version'] <= $current_version) {
        if (!isset($info['path'])) {
          $info['path'] = drupal_get_path('module', $module);
        }
        $cache[$owner][$api][$module] = $info;
      }
    }

    // And allow themes to implement these as well.
    $themes = _ctools_list_themes();
    foreach ($themes as $name => $theme) {
      if (!empty($theme->info['api'][$owner][$api])) {
        $info = $theme->info['api'][$owner][$api];
        if (!isset($info['version'])) {
          continue;
        }

        // Only process if version is between minimum and current, inclusive.
        if ($info['version'] >= $minimum_version && $info['version'] <= $current_version) {
          if (!isset($info['path'])) {
            $info['path'] = '';
          }

          // Because themes can't easily specify full path, we add it here
          // even though we do not for modules:
          $info['path'] = drupal_get_path('theme', $name) . '/' . $info['path'];
          $cache[$owner][$api][$name] = $info;
        }
      }
    }
  }
  return $cache[$owner][$api];
}