[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: ctools.api.php,v 1.1.2.1 2010/06/06 20:16:17 sdboyer Exp $
   3  
   4  /**
   5   * @file
   6   * Hooks provided by the Chaos Tool Suite.
   7   *
   8   * This file is divided into static hooks (hooks with string literal names) and
   9   * dynamic hooks (hooks with pattern-derived string names).
  10   */
  11  
  12  /**
  13   * @addtogroup hooks
  14   * @{
  15   */
  16  
  17  /**
  18   * This hook is used to inform the CTools plugin system about the location of a
  19   * directory that should be searched for files containing plugins of a
  20   * particular type. CTools invokes this same hook for all plugins, using the
  21   * two passed parameters to indicate the specific type of plugin for which it
  22   * is searching.
  23   *
  24   * The $plugin_type parameter is self-explanatory - it is the string name of the
  25   * plugin type (e.g., Panels' 'layouts' or 'styles'). The $owner parameter is
  26   * necessary because CTools internally namespaces plugins by the module that
  27   * owns them. This is an extension of Drupal best practices on avoiding global
  28   * namespace pollution by prepending your module name to all its functions.
  29   * Consequently, it is possible for two different modules to create a plugin
  30   * type with exactly the same name and have them operate in harmony. In fact,
  31   * this system renders it impossible for modules to encroach on other modules'
  32   * plugin namespaces.
  33   *
  34   * Given this namespacing, it is important that implementations of this hook
  35   * check BOTH the $owner and $plugin_type parameters before returning a path.
  36   * If your module does not implement plugins for the requested module/plugin
  37   * combination, it is safe to return nothing at all (or NULL). As a convenience,
  38   * it is also safe to return a path that does not exist for plugins your module
  39   * does not implement - see form 2 for a use case.
  40   *
  41   * Note that modules implementing a plugin also must implement this hook to
  42   * instruct CTools as to the location of the plugins. See form 3 for a use case.
  43   *
  44   * The conventional structure to return is "plugins/$plugin_type" - that is, a
  45   * 'plugins' subdirectory in your main module directory, with individual
  46   * directories contained therein named for the plugin type they contain.
  47   *
  48   * @param string $owner
  49   *   The system name of the module owning the plugin type for which a base
  50   *   directory location is being requested.
  51   * @param string $plugin_type
  52   *   The name of the plugin type for which a base directory is being requested.
  53   * @return string
  54   *   The path where CTools' plugin system should search for plugin files,
  55   *   relative to your module's root. Omit leading and trailing slashes.
  56   */
  57  function hook_ctools_plugin_directory($owner, $plugin_type) {
  58    // Form 1 - for a module implementing only the 'content_types' plugin owned
  59    // by CTools, this would cause the plugin system to search the
  60    // <moduleroot>/plugins/content_types directory for .inc plugin files.
  61    if ($owner == 'ctools' && $plugin_type == 'content_types') {
  62      return 'plugins/content_types';
  63    }
  64  
  65    // Form 2 - if your module implements only Panels plugins, and has 'layouts'
  66    // and 'styles' plugins but no 'cache' or 'display_renderers', it is OK to be
  67    // lazy and return a directory for a plugin you don't actually implement (so
  68    // long as that directory doesn't exist). This lets you avoid ugly in_array()
  69    // logic in your conditional, and also makes it easy to add plugins of those
  70    // types later without having to change this hook implementation.
  71    if ($owner == 'panels') {
  72      return "plugins/$plugin_type";
  73    }
  74  
  75    // Form 3 - CTools makes no assumptions about where your plugins are located,
  76    // so you still have to implement this hook even for plugins created by your
  77    // own module.
  78    if ($owner == 'mymodule') {
  79      // Yes, this is exactly like Form 2 - just a different reasoning for it.
  80      return "plugins/$plugin_type";
  81    }
  82    // Finally, if nothing matches, it's safe to return nothing at all (or NULL).
  83  }
  84  
  85  /**
  86   * @} End of "addtogroup hooks".
  87   */