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