|
1
|
<p>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.</p>
|
|
2
|
|
|
3
|
<p>Modules support this API by implementing hook_ctools_plugin_api($module, $api). If they support the API, they return a packet of data:</p>
|
|
4
|
|
|
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
|
<p>This implementation must be in the .module file.</p>
|
|
18
|
|
|
19
|
<p>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:</p>
|
|
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
|
<p>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:</p>
|
|
32
|
|
|
33
|
<pre>
|
|
34
|
mymodule_include_api();
|
|
35
|
module_invoke('myhook', $data);
|
|
36
|
</pre>
|
|
37
|
|
|
38
|
<p>If you need to pass references, this construct is standard:</p>
|
|
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
|
<p>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.</p>
|
