ctools.api.php 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the Chaos Tool Suite.
  5. *
  6. * This file is divided into static hooks (hooks with string literal names) and
  7. * dynamic hooks (hooks with pattern-derived string names).
  8. */
  9. /**
  10. * @addtogroup hooks
  11. * @{
  12. */
  13. /**
  14. * Inform CTools about plugin types.
  15. *
  16. * @return array
  17. * An array of plugin types, keyed by the type name.
  18. * See the advanced help topic 'plugins-creating' for details of the array
  19. * properties.
  20. */
  21. function hook_ctools_plugin_type() {
  22. $plugins['my_type'] = array(
  23. 'load themes' => TRUE,
  24. );
  25. return $plugins;
  26. }
  27. /**
  28. * This hook is used to inform the CTools plugin system about the location of a
  29. * directory that should be searched for files containing plugins of a
  30. * particular type. CTools invokes this same hook for all plugins, using the
  31. * two passed parameters to indicate the specific type of plugin for which it
  32. * is searching.
  33. *
  34. * The $plugin_type parameter is self-explanatory - it is the string name of the
  35. * plugin type (e.g., Panels' 'layouts' or 'styles'). The $owner parameter is
  36. * necessary because CTools internally namespaces plugins by the module that
  37. * owns them. This is an extension of Drupal best practices on avoiding global
  38. * namespace pollution by prepending your module name to all its functions.
  39. * Consequently, it is possible for two different modules to create a plugin
  40. * type with exactly the same name and have them operate in harmony. In fact,
  41. * this system renders it impossible for modules to encroach on other modules'
  42. * plugin namespaces.
  43. *
  44. * Given this namespacing, it is important that implementations of this hook
  45. * check BOTH the $owner and $plugin_type parameters before returning a path.
  46. * If your module does not implement plugins for the requested module/plugin
  47. * combination, it is safe to return nothing at all (or NULL). As a convenience,
  48. * it is also safe to return a path that does not exist for plugins your module
  49. * does not implement - see form 2 for a use case.
  50. *
  51. * Note that modules implementing a plugin also must implement this hook to
  52. * instruct CTools as to the location of the plugins. See form 3 for a use case.
  53. *
  54. * The conventional structure to return is "plugins/$plugin_type" - that is, a
  55. * 'plugins' subdirectory in your main module directory, with individual
  56. * directories contained therein named for the plugin type they contain.
  57. *
  58. * @param string $owner
  59. * The system name of the module owning the plugin type for which a base
  60. * directory location is being requested.
  61. * @param string $plugin_type
  62. * The name of the plugin type for which a base directory is being requested.
  63. * @return string
  64. * The path where CTools' plugin system should search for plugin files,
  65. * relative to your module's root. Omit leading and trailing slashes.
  66. */
  67. function hook_ctools_plugin_directory($owner, $plugin_type) {
  68. // Form 1 - for a module implementing only the 'content_types' plugin owned
  69. // by CTools, this would cause the plugin system to search the
  70. // <moduleroot>/plugins/content_types directory for .inc plugin files.
  71. if ($owner == 'ctools' && $plugin_type == 'content_types') {
  72. return 'plugins/content_types';
  73. }
  74. // Form 2 - if your module implements only Panels plugins, and has 'layouts'
  75. // and 'styles' plugins but no 'cache' or 'display_renderers', it is OK to be
  76. // lazy and return a directory for a plugin you don't actually implement (so
  77. // long as that directory doesn't exist). This lets you avoid ugly in_array()
  78. // logic in your conditional, and also makes it easy to add plugins of those
  79. // types later without having to change this hook implementation.
  80. if ($owner == 'panels') {
  81. return "plugins/$plugin_type";
  82. }
  83. // Form 3 - CTools makes no assumptions about where your plugins are located,
  84. // so you still have to implement this hook even for plugins created by your
  85. // own module.
  86. if ($owner == 'mymodule') {
  87. // Yes, this is exactly like Form 2 - just a different reasoning for it.
  88. return "plugins/$plugin_type";
  89. }
  90. // Finally, if nothing matches, it's safe to return nothing at all (or NULL).
  91. }
  92. /**
  93. * Alter a plugin before it has been processed.
  94. *
  95. * This hook is useful for altering flags or other information that will be
  96. * used or possibly overriden by the process hook if defined.
  97. *
  98. * @param $plugin
  99. * An associative array defining a plugin.
  100. * @param $info
  101. * An associative array of plugin type info.
  102. */
  103. function hook_ctools_plugin_pre_alter(&$plugin, &$info) {
  104. // Override a function defined by the plugin.
  105. if ($info['type'] == 'my_type') {
  106. $plugin['my_flag'] = 'new_value';
  107. }
  108. }
  109. /**
  110. * Alter a plugin after it has been processed.
  111. *
  112. * This hook is useful for overriding the final values for a plugin after it
  113. * has been processed.
  114. *
  115. * @param $plugin
  116. * An associative array defining a plugin.
  117. * @param $info
  118. * An associative array of plugin type info.
  119. */
  120. function hook_ctools_plugin_post_alter(&$plugin, &$info) {
  121. // Override a function defined by the plugin.
  122. if ($info['type'] == 'my_type') {
  123. $plugin['my_function'] = 'new_function';
  124. }
  125. }
  126. /**
  127. * Alter the list of modules/themes which implement a certain api.
  128. *
  129. * The hook named here is just an example, as the real existing hooks are named
  130. * for example 'hook_views_api_alter'.
  131. *
  132. * @param array $list
  133. * An array of informations about the implementors of a certain api.
  134. * The key of this array are the module names/theme names.
  135. */
  136. function hook_ctools_api_hook_alter(&$list) {
  137. // Alter the path of the node implementation.
  138. $list['node']['path'] = drupal_get_path('module', 'node');
  139. }
  140. /**
  141. * Alter the available functions to be used in ctools math expression api.
  142. *
  143. * One usecase would be to create your own function in your module and
  144. * allow to use it in the math expression api.
  145. *
  146. * @param $functions
  147. * An array which has the functions as value.
  148. */
  149. function hook_ctools_math_expression_functions_alter(&$functions) {
  150. // Allow to convert from degrees to radiant.
  151. $functions[] = 'deg2rad';
  152. }
  153. /**
  154. * Alter everything.
  155. *
  156. * @param $info
  157. * An associative array containing the following keys:
  158. * - content: The rendered content.
  159. * - title: The content's title.
  160. * - no_blocks: A boolean to decide if blocks should be displayed.
  161. * @param $page
  162. * If TRUE then this renderer owns the page and can use theme('page')
  163. * for no blocks; if false, output is returned regardless of any no
  164. * blocks settings.
  165. * @param $context
  166. * An associative array containing the following keys:
  167. * - args: The raw arguments behind the contexts.
  168. * - contexts: The context objects in use.
  169. * - task: The task object in use.
  170. * - subtask: The subtask object in use.
  171. * - handler: The handler object in use.
  172. */
  173. function hook_ctools_render_alter(&$info, &$page, &$context) {
  174. if ($context['handler']->name == 'my_handler') {
  175. ctools_add_css('my_module.theme', 'my_module');
  176. }
  177. }
  178. /**
  179. * Alter a content plugin subtype.
  180. *
  181. * While content types can be altered via hook_ctools_plugin_pre_alter() or
  182. * hook_ctools_plugin_post_alter(), the subtypes that content types rely on
  183. * are special and require their own hook.
  184. *
  185. * This hook can be used to add things like 'render last' or change icons
  186. * or categories or to rename content on specific sites.
  187. */
  188. function hook_ctools_content_subtype_alter($subtype, $plugin) {
  189. // Force a particular subtype of a particular plugin to render last.
  190. if ($plugin['module'] == 'some_plugin_module' && $plugin['name'] == 'some_plugin_name' && $subtype['subtype_id'] == 'my_subtype_id') {
  191. $subtype['render last'] = TRUE;
  192. }
  193. }
  194. /**
  195. * Alter the definition of an entity context plugin.
  196. *
  197. * @param array $plugin
  198. * An associative array defining a plugin.
  199. * @param array $entity
  200. * The entity info array of a specific entity type.
  201. * @param string $plugin_id
  202. * The plugin ID, in the format NAME:KEY.
  203. */
  204. function hook_ctools_entity_context_alter(&$plugin, &$entity, $plugin_id) {
  205. ctools_include('context');
  206. switch ($plugin_id) {
  207. case 'entity_id:taxonomy_term':
  208. $plugin['no ui'] = TRUE;
  209. case 'entity:user':
  210. $plugin = ctools_get_context('user');
  211. unset($plugin['no ui']);
  212. unset($plugin['no required context ui']);
  213. break;
  214. }
  215. }
  216. /**
  217. * Alter the definition of entity context plugins.
  218. *
  219. * @param array $plugins
  220. * An associative array of plugin definitions, keyed by plugin ID.
  221. *
  222. * @see hook_ctools_entity_context_alter()
  223. */
  224. function hook_ctools_entity_contexts_alter(&$plugins) {
  225. $plugins['entity_id:taxonomy_term']['no ui'] = TRUE;
  226. }
  227. /**
  228. * Change cleanstring settings.
  229. *
  230. * @param array $settings
  231. * An associative array of cleanstring settings.
  232. *
  233. * @see ctools_cleanstring()
  234. */
  235. function hook_ctools_cleanstring_alter(&$settings) {
  236. // Convert all strings to lower case.
  237. $settings['lower case'] = TRUE;
  238. }
  239. /**
  240. * Change cleanstring settings for a specific clean ID.
  241. *
  242. * @param array $settings
  243. * An associative array of cleanstring settings.
  244. *
  245. * @see ctools_cleanstring()
  246. */
  247. function hook_ctools_cleanstring_CLEAN_ID_alter(&$settings) {
  248. // Convert all strings to lower case.
  249. $settings['lower case'] = TRUE;
  250. }
  251. /**
  252. * @} End of "addtogroup hooks".
  253. */