aDriv4 - MANAGER

Edit File: plugins-implementing.html

<p>There are two parts to implementing a plugin: telling the system where it is, and implementing one or more .inc files that contain the plugin data.</p>

<h2>Telling the system where your plugins live</h2>
<h3>How a module implements plugins</h3>
<p>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.</p>

<pre>
function hook_ctools_plugin_directory($module, $plugin) {
  if ($module == 'panels' && $plugin == 'content_types') {
    return 'plugins/content_types';
  }
}
</pre>

<p>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):</p>

<pre>
function hook_ctools_plugin_directory($module, $plugin) {
  if ($module == 'panels') {
    return 'plugins/' . $plugin;
  }
}
</pre>

<p>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:</p>
<pre>
mymodule.module
mymodule.info
plugins/
    content_types/
        my_content_type.inc
    layouts/
        my_layout.inc
        my_layout.css
        my_layout.tpl.php
        my_layout_image.png
</pre>

<h3>How a theme implements plugins</h3>
<p>Themes can implement plugins if the plugin owner specified that it's possible in its hook_ctools_plugin_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:</p>

<pre>
plugins[module][type] = directory
</pre>

<h2>How to structure the .inc file</h2>

<p>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.</p>

<p>This array should look something like this:</p>

<pre>
$plugin = array(
  'key' => 'value',
);
</pre>

<p>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 owner can provide other defaults as well.</p>

<p>There are no required keys by the plugin system itself. The only requirements in the $plugin array will be defined by the plugin type.</p>

<p>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.</p>