[Summary view] [Print] [Text view]

   1  <!-- $Id: plugins-implementing.html,v 1.3.2.1 2009/11/13 00:44:16 merlinofchaos Exp $ -->
   2  To implement plugins, you need to implement a single hook in your module to tell the system where your plugins live, and then you need to implement one or more .inc files that contain the plugin data.
   3  
   4  <h3>Telling it where your plugins live</h3>
   5  To implement any plugins at all, you must implement a single function for all plugins: <strong>hook_ctools_plugin_directory</strong>. Every time a module loads plugins, this hook will be called to see which modules implement those plugins and in what directory those plugins will live.
   6  
   7  <pre>
   8  function hook_ctools_plugin_directory($module, $plugin) {
   9    if ($module == 'panels' && $plugin == 'content_types') {
  10      return 'plugins/content_types';
  11    }
  12  }
  13  </pre>
  14  
  15  The directory returned should be relative to your module. Another common usage is to simply return that you implement all plugins owned by a given module (or modules):
  16  
  17  <pre>
  18  function hook_ctools_plugin_directory($module, $plugin) {
  19    if ($module == 'panels') {
  20      return 'plugins/' . $plugin;
  21    }
  22  }
  23  </pre>
  24  
  25  Typically, it is recommended that all plugins be placed into the 'plugins' directory for clarity and maintainability. Inside the directory, any number of subdirectories can be used. For plugins that require extra files, such as templates, css, javascript or image files, this is highly recommended:
  26  <pre>
  27  mymodule.module
  28  mymodule.info
  29  plugins/
  30      content_types/
  31          my_content_type.inc
  32      layouts/
  33          my_layout.inc
  34          my_laout.css
  35          my_layout.tpl.php
  36          my_layout_image.png
  37  </pre>
  38  
  39  <h3>How a theme can implement plugins</h3>
  40  Themes can implement plugins if the plugin owner specified that it's possible in its hook_ctools_api_TYPE() call. If so, it is generally exactly the same as modules, except for one important difference: themes don't get hook_ctools_plugin_directory(). Instead, themes add a line to their info file:
  41  
  42  <pre>
  43  plugins[module][type] = directory
  44  </pre>
  45  
  46  <h3>How to structure the .inc file</h3>
  47  
  48  The top of the .inc file should contain an array that defines the plugin. This array is simply defined in the global namespace of the file and does not need a function. Note that previous versions of this plugin system required a specially named function. While this function will still work, its use is now discouraged, as it is annoying to name properly.
  49  
  50  This array should look something like this:
  51  <pre>
  52  $plugin = array(
  53    'key' => 'value',
  54  );
  55  </pre>
  56  
  57  Several values will be filled in for you automatically, but you can override them if necessary. They include 'name', 'path', 'file' and 'module'. Additionally, the plugin can owner can provide other defaults as well.
  58  
  59  After this array, if your plugin needs functions, they can be declared. Different plugin types have different needs here, so exactly what else will be needed will change from type to type.