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