[Summary view] [Print] [Text view]

   1  <!-- $Id: plugins-api.html,v 1.3 2009/04/17 19:16:21 merlinofchaos Exp $ -->
   2  APIs are a form of plugins that are tightly associated with a module. Instead of a module providing any number of plugins, each module provides only one file for an API and this file can contain hooks that the module should invoke.
   3  
   4  Modules support this API by implementing hook_ctools_plugin_api($module, $api). If they support the API, they return a packet of data:
   5  <pre>
   6  function mymodule_ctools_plugin_api($module, $api) {
   7    if ($module == 'some module' && $api = 'some api') {
   8      return array(
   9        'version' => The minimum API version this system supports. If this API version is incompatible then the .inc file will not be loaded.
  10        'path' => Where to find the file. Optional; if not specified it will be the module's directory.
  11        'file' => an alternative version of the filename. If not specified it will be $module.$api.inc
  12      );
  13    }
  14  }
  15  </pre>
  16  
  17  This implementation must be in the .module file.
  18  
  19  Modules utilizing this can invole ctools_plugin_api_include() in order to ensure all modules that support the API will have their files loaded as necessary. It's usually easiest to create a small helper function like this:
  20  
  21  <pre>
  22  define('MYMODULE_MINIMUM_VERSION', 1);
  23  define('MYMODULE_VERSION', 1);
  24  
  25  function mymodule_include_api() {
  26    ctools_include('plugins');
  27    return ctools_plugin_api_include('mymodule', 'myapi', MYMODULE_MINIMUM_VERSION, MYMODULE_VERSION);
  28  }
  29  </pre>
  30  
  31  Using a define will ensure your use of version numbers is consistent and easy to update when you make API changes. You can then use the usual module_invoke type commands:
  32  
  33  <pre>
  34  mymodule_include_api();
  35  module_invoke('myhook', $data);
  36  </pre>
  37  
  38  If you need to pass references, this construct is standard:
  39  
  40  <pre>
  41  foreach (mymodule_include_api() as $module => $info) {
  42    $function = $module . '_hookname';
  43    // Just because they implement the API and include a file does not guarantee they implemented
  44    // a hook function!
  45    if (!function_exists($function)) {
  46      continue;
  47    }
  48  
  49    // Typically array_merge() is used below if data is returned.
  50    $result = $function($data1, $data2, $data3);
  51  }
  52  </pre>
  53  
  54  TODO: There needs to be a way to check API version without including anything, as a module may simply
  55  provide normal plugins and versioning could still matter.