There are two primary pieces to using plugins. The first is getting the data, and the second is using the data.
ctools_include('plugins'); ctools_get_plugins($module, $type, [$id])In the above example, $module should be your module's name and $type is the type of the plugin. It is typically best practice to provide some kind of wrapper function to make this easier. For example, Panels provides the following functions to implement the 'content_types' plugin:
/** * Fetch metadata on a specific content_type plugin. * * @param $content type * Name of a panel content type. * * @return * An array with information about the requested panel content type. */ function panels_get_content_type($content_type) { ctools_include('context'); ctools_include('plugins'); return ctools_get_plugins('panels', 'content_types', $content_type); } /** * Fetch metadata for all content_type plugins. * * @return * An array of arrays with information about all available panel content types. */ function panels_get_content_types() { ctools_include('context'); ctools_include('plugins'); return ctools_get_plugins('panels', 'content_types'); }As a plugin creator, your module can also implement a hook to give more information about this plugin, and to enable a few features that are not normally enabled. If you need any of these features, simply implement hook_ctools_plugin_TYPE (where TYPE is the same $type sent to ctools_get_plugins). This isn't a true hook, it will only be called for the $module that was given. This hook returns an array:
/** * Inform CTools that the layout plugin can be loaded from themes. */ function panels_ctools_plugin_layouts() { return array( 'load themes' => TRUE, ); }The following information can be specified:
/** * Get a function from a plugin, if it exists. If the plugin is not already * loaded, try ctools_plugin_load_function() instead. * * @param $plugin * The loaded plugin type. * @param $callback_name * The identifier of the function. For example, 'settings form'. * * @return * The actual name of the function to call, or NULL if the function * does not exist. */ function ctools_plugin_get_function($plugin, $callback_name)The second does not require the full $plugin object, and will load it:
/** * Load a plugin and get a function name from it, returning success only * if the function exists. * * @param $module * The module that owns the plugin type. * @param $type * The type of plugin. * @param $id * The id of the specific plugin to load. * @param $callback_name * The identifier of the function. For example, 'settings form'. * * @return * The actual name of the function to call, or NULL if the function * does not exist. */ function ctools_plugin_load_function($module, $type, $id, $callback_name) {Both of these functions will ensure any needed files are included. In fact, it allows each callback to specify alternative include files. The plugin implementation could include code like this:
'callback_name' => 'actual_name_of_function_here',Or like this:
'callback_name' => array( 'file' => 'filename', 'path' => 'filepath', // optional, will use plugin path if absent 'function' => 'actual_name_of_function_here', ),An example, for 'plugin_example' type
$plugin = array( 'name' => 'my_plugin', 'module' => 'my_module', 'example_callback' => array( 'file' => 'my_plugin.extrafile.inc', 'function' => 'my_module_my_plugin_example_callback', ), );To utilize this callback on this plugin:
if ($function = ctools_plugin_get_function($plugin, 'example_callback')) { $function($arg1, $arg2, $etc); }