root / drupal7 / sites / all / modules / libraries / libraries.api.php @ 64ad485a
1 | 85ad3d82 | Assos Assos | <?php
|
---|---|---|---|
2 | |||
3 | /**
|
||
4 | * @file
|
||
5 | * Documents API functions for Libraries module.
|
||
6 | */
|
||
7 | |||
8 | /**
|
||
9 | * Return information about external libraries.
|
||
10 | *
|
||
11 | * @return
|
||
12 | * An associative array whose keys are internal names of libraries and whose
|
||
13 | * values are describing each library. Each key is the directory name below
|
||
14 | * the 'libraries' directory, in which the library may be found. Each value is
|
||
15 | * an associative array containing:
|
||
16 | * - name: The official, human-readable name of the library.
|
||
17 | * - vendor url: The URL of the homepage of the library.
|
||
18 | * - download url: The URL of a web page on which the library can be obtained.
|
||
19 | * - path: (optional) A relative path from the directory of the library to the
|
||
20 | * actual library. Only required if the extracted download package contains
|
||
21 | * the actual library files in a sub-directory.
|
||
22 | * - library path: (optional) The absolute path to the library directory. This
|
||
23 | * should not be declared normally, as it is automatically detected, to
|
||
24 | * allow for multiple possible library locations. A valid use-case is an
|
||
25 | * external library, in which case the full URL to the library should be
|
||
26 | * specified here.
|
||
27 | * - version: (optional) The version of the library. This should not be
|
||
28 | * declared normally, as it is automatically detected (see 'version
|
||
29 | * callback' below) to allow for version changes of libraries without code
|
||
30 | * changes of implementing modules and to support different versions of a
|
||
31 | * library simultaneously (though only one version can be installed per
|
||
32 | * site). A valid use-case is an external library whose version cannot be
|
||
33 | 3753f249 | Assos Assos | * determined programmatically. Either 'version' or 'version callback' (or
|
34 | * 'version arguments' in case libraries_get_version() is being used as a
|
||
35 | * version callback) must be declared.
|
||
36 | 85ad3d82 | Assos Assos | * - version callback: (optional) The name of a function that detects and
|
37 | * returns the full version string of the library. The first argument is
|
||
38 | * always $library, an array containing all library information as described
|
||
39 | * here. There are two ways to declare the version callback's additional
|
||
40 | * arguments, either as a single $options parameter or as multiple
|
||
41 | * parameters, which correspond to the two ways to specify the argument
|
||
42 | * values (see 'version arguments'). Defaults to libraries_get_version().
|
||
43 | 3753f249 | Assos Assos | * Unless 'version' is declared or libraries_get_version() is being used as
|
44 | * a version callback, 'version callback' must be declared. In the latter
|
||
45 | * case, however, 'version arguments' must be declared in the specified way.
|
||
46 | * - version arguments: (optional) A list of arguments to pass to the version
|
||
47 | * callback. Version arguments can be declared either as an associative
|
||
48 | * array whose keys are the argument names or as an indexed array without
|
||
49 | * specifying keys. If declared as an associative array, the arguments get
|
||
50 | * passed to the version callback as a single $options parameter whose keys
|
||
51 | * are the argument names (i.e. $options is identical to the specified
|
||
52 | * array). If declared as an indexed array, the array values get passed to
|
||
53 | * the version callback as separate arguments in the order they were
|
||
54 | * declared. The default version callback libraries_get_version() expects a
|
||
55 | * single, associative array with named keys:
|
||
56 | * - file: The filename to parse for the version, relative to the path
|
||
57 | * speficied as the 'library path' property (see above). For example:
|
||
58 | * 'docs/changelog.txt'.
|
||
59 | 85ad3d82 | Assos Assos | * - pattern: A string containing a regular expression (PCRE) to match the
|
60 | * library version. For example: '@version\s+([0-9a-zA-Z\.-]+)@'. Note
|
||
61 | * that the returned version is not the match of the entire pattern (i.e.
|
||
62 | * '@version 1.2.3' in the above example) but the match of the first
|
||
63 | * sub-pattern (i.e. '1.2.3' in the above example).
|
||
64 | * - lines: (optional) The maximum number of lines to search the pattern in.
|
||
65 | * Defaults to 20.
|
||
66 | * - cols: (optional) The maximum number of characters per line to take into
|
||
67 | * account. Defaults to 200. In case of minified or compressed files, this
|
||
68 | * prevents reading the entire file into memory.
|
||
69 | 3753f249 | Assos Assos | * Defaults to an empty array. 'version arguments' must be specified unless
|
70 | * 'version' is declared or the specified 'version callback' does not
|
||
71 | * require any arguments. The latter might be the case with a
|
||
72 | * library-specific version callback, for example.
|
||
73 | 85ad3d82 | Assos Assos | * - files: An associative array of library files to load. Supported keys are:
|
74 | * - js: A list of JavaScript files to load, using the same syntax as Drupal
|
||
75 | * core's hook_library().
|
||
76 | * - css: A list of CSS files to load, using the same syntax as Drupal
|
||
77 | * core's hook_library().
|
||
78 | * - php: A list of PHP files to load.
|
||
79 | * - dependencies: An array of libraries this library depends on. Similar to
|
||
80 | * declaring module dependencies, the dependency declaration may contain
|
||
81 | * information on the supported version. Examples of supported declarations:
|
||
82 | * @code
|
||
83 | * $libraries['dependencies'] = array(
|
||
84 | * // Load the 'example' library, regardless of the version available:
|
||
85 | * 'example',
|
||
86 | * // Only load the 'example' library, if version 1.2 is available:
|
||
87 | * 'example (1.2)',
|
||
88 | * // Only load a version later than 1.3-beta2 of the 'example' library:
|
||
89 | * 'example (>1.3-beta2)'
|
||
90 | * // Only load a version equal to or later than 1.3-beta3:
|
||
91 | * 'example (>=1.3-beta3)',
|
||
92 | * // Only load a version earlier than 1.5:
|
||
93 | * 'example (<1.5)',
|
||
94 | * // Only load a version equal to or earlier than 1.4:
|
||
95 | * 'example (<=1.4)',
|
||
96 | * // Combinations of the above are allowed as well:
|
||
97 | * 'example (>=1.3-beta2, <1.5)',
|
||
98 | * );
|
||
99 | * @endcode
|
||
100 | * - variants: (optional) An associative array of available library variants.
|
||
101 | * For example, the top-level 'files' property may refer to a default
|
||
102 | * variant that is compressed. If the library also ships with a minified and
|
||
103 | * uncompressed/source variant, those can be defined here. Each key should
|
||
104 | * describe the variant type, e.g. 'minified' or 'source'. Each value is an
|
||
105 | * associative array of top-level properties that are entirely overridden by
|
||
106 | * the variant, most often just 'files'. Additionally, each variant can
|
||
107 | * contain following properties:
|
||
108 | * - variant callback: (optional) The name of a function that detects the
|
||
109 | * variant and returns TRUE or FALSE, depending on whether the variant is
|
||
110 | * available or not. The first argument is always $library, an array
|
||
111 | * containing all library information as described here. The second
|
||
112 | * argument is always a string containing the variant name. There are two
|
||
113 | 3753f249 | Assos Assos | * ways to declare the variant callback's additional arguments, either as a
|
114 | 85ad3d82 | Assos Assos | * single $options parameter or as multiple parameters, which correspond
|
115 | * to the two ways to specify the argument values (see 'variant
|
||
116 | 3753f249 | Assos Assos | * arguments'). If omitted, the variant is expected to always be
|
117 | 85ad3d82 | Assos Assos | * available.
|
118 | * - variant arguments: A list of arguments to pass to the variant callback.
|
||
119 | * Variant arguments can be declared either as an associative array whose
|
||
120 | * keys are the argument names or as an indexed array without specifying
|
||
121 | * keys. If declared as an associative array, the arguments get passed to
|
||
122 | * the variant callback as a single $options parameter whose keys are the
|
||
123 | * argument names (i.e. $options is identical to the specified array). If
|
||
124 | * declared as an indexed array, the array values get passed to the
|
||
125 | 3753f249 | Assos Assos | * variant callback as separate arguments in the order they were declared.
|
126 | 85ad3d82 | Assos Assos | * Variants can be version-specific (see 'versions').
|
127 | * - versions: (optional) An associative array of supported library versions.
|
||
128 | * Naturally, libraries evolve over time and so do their APIs. In case a
|
||
129 | * library changes between versions, different 'files' may need to be
|
||
130 | * loaded, different 'variants' may become available, or Drupal modules need
|
||
131 | * to load different integration files adapted to the new version. Each key
|
||
132 | * is a version *string* (PHP does not support floats as keys). Each value
|
||
133 | * is an associative array of top-level properties that are entirely
|
||
134 | * overridden by the version.
|
||
135 | * - integration files: (optional) An associative array whose keys are module
|
||
136 | * names and whose values are sets of files to load for the module, using
|
||
137 | * the same notion as the top-level 'files' property. Each specified file
|
||
138 | * should contain the path to the file relative to the module it belongs to.
|
||
139 | * - callbacks: An associative array whose keys are callback groups and whose
|
||
140 | * values are arrays of callbacks to apply to the library in that group.
|
||
141 | * Each callback receives the following arguments:
|
||
142 | * - $library: An array of library information belonging to the top-level
|
||
143 | * library, a specific version, a specific variant or a specific variant
|
||
144 | * of a specific version. Because library information such as the 'files'
|
||
145 | * property (see above) can be declared in all these different locations
|
||
146 | * of the library array, but a callback may have to act on all these
|
||
147 | * different parts of the library, it is called recursively for each
|
||
148 | * library with a certain part of the libraries array passed as $library
|
||
149 | * each time.
|
||
150 | * - $version: If the $library array belongs to a certain version (see
|
||
151 | * above), a string containing the version. This argument may be empty, so
|
||
152 | * NULL should be specified as the default value.
|
||
153 | * - $variant: If the $library array belongs to a certain variant (see
|
||
154 | * above), a string containing the variant name. This argument may be
|
||
155 | * empty, so NULL should be specified as the default value.
|
||
156 | * Valid callback groups are:
|
||
157 | * - info: Callbacks registered in this group are applied after the library
|
||
158 | * information has been retrieved via hook_libraries_info() or info files.
|
||
159 | 3753f249 | Assos Assos | * At this point the following additional information is available:
|
160 | * - $library['info type']: How the library information was obtained. Can
|
||
161 | * be 'info file', 'module', or 'theme', depending on whether the
|
||
162 | * library information was obtained from an info file, an enabled module
|
||
163 | * or an enabled theme, respectively.
|
||
164 | * Additionally, one of the following three keys is available, depending
|
||
165 | * on the value of $library['info type'].
|
||
166 | * - $library['info file']: In case the library information was obtained
|
||
167 | * from an info file, the URI of the info file.
|
||
168 | * - $library['module']: In case the library was obtained from an enabled
|
||
169 | * module, the name of the providing module.
|
||
170 | * - $library['theme']: In case the library was obtained from an enabled
|
||
171 | * theme, the name of the providing theme.
|
||
172 | 85ad3d82 | Assos Assos | * - pre-detect: Callbacks registered in this group are applied after the
|
173 | * library path has been determined and before the version callback is
|
||
174 | 3753f249 | Assos Assos | * invoked. At this point the following additional information is
|
175 | * available:
|
||
176 | 85ad3d82 | Assos Assos | * - $library['library path']: The path on the file system to the library.
|
177 | * - post-detect: Callbacks registered in this group are applied after the
|
||
178 | * library has been successfully detected. At this point the library
|
||
179 | * contains the version-specific information, if specified, and following
|
||
180 | * additional information is available:
|
||
181 | * - $library['installed']: A boolean indicating whether the library is
|
||
182 | * installed or not.
|
||
183 | * - $library['version']: If it could be detected, a string containing the
|
||
184 | * version of the library.
|
||
185 | * - $library['variants'][$variant]['installed']: For each specified
|
||
186 | * variant, a boolean indicating whether the variant is installed or
|
||
187 | * not.
|
||
188 | * Note that in this group the 'versions' property is no longer available.
|
||
189 | * - pre-dependencies-load: Callbacks registered in this group are applied
|
||
190 | * directly before the library's dependencies are loaded. At this point
|
||
191 | * the library contains variant-specific information, if specified. Note
|
||
192 | * that in this group the 'variants' property is no longer available.
|
||
193 | * - pre-load: Callbacks registered in this group are applied directly after
|
||
194 | * the library's dependencies are loaded and before the library itself is
|
||
195 | * loaded.
|
||
196 | * - post-load: Callbacks registered in this group are applied directly
|
||
197 | * after this library is loaded. At this point, the library contains a
|
||
198 | * 'loaded' key, which contains the number of files that were loaded.
|
||
199 | * Additional top-level properties can be registered as needed.
|
||
200 | *
|
||
201 | * @see hook_library()
|
||
202 | */
|
||
203 | function hook_libraries_info() { |
||
204 | // The following is a full explanation of all properties. See below for more
|
||
205 | // concrete example implementations.
|
||
206 | |||
207 | // This array key lets Libraries API search for 'sites/all/libraries/example'
|
||
208 | // directory, which should contain the entire, original extracted library.
|
||
209 | $libraries['example'] = array( |
||
210 | // Only used in administrative UI of Libraries API.
|
||
211 | 'name' => 'Example library', |
||
212 | 'vendor url' => 'http://example.com', |
||
213 | 'download url' => 'http://example.com/download', |
||
214 | // Optional: If, after extraction, the actual library files are contained in
|
||
215 | // 'sites/all/libraries/example/lib', specify the relative path here.
|
||
216 | 'path' => 'lib', |
||
217 | // Optional: Define a custom version detection callback, if required.
|
||
218 | 'version callback' => 'mymodule_get_version', |
||
219 | // Specify arguments for the version callback. By default,
|
||
220 | // libraries_get_version() takes a named argument array:
|
||
221 | 'version arguments' => array( |
||
222 | 'file' => 'docs/CHANGELOG.txt', |
||
223 | 'pattern' => '@version\s+([0-9a-zA-Z\.-]+)@', |
||
224 | 'lines' => 5, |
||
225 | 'cols' => 20, |
||
226 | ), |
||
227 | // Default list of files of the library to load. Important: Only specify
|
||
228 | // third-party files belonging to the library here, not integration files of
|
||
229 | // your module.
|
||
230 | 'files' => array( |
||
231 | // 'js' and 'css' follow the syntax of hook_library(), but file paths are
|
||
232 | // relative to the library path.
|
||
233 | 'js' => array( |
||
234 | 'exlib.js',
|
||
235 | 'gadgets/foo.js',
|
||
236 | ), |
||
237 | 'css' => array( |
||
238 | 'lib_style.css',
|
||
239 | 'skin/example.css',
|
||
240 | ), |
||
241 | // For PHP libraries, specify include files here, still relative to the
|
||
242 | // library path.
|
||
243 | 'php' => array( |
||
244 | 'exlib.php',
|
||
245 | 'exlib.inc',
|
||
246 | ), |
||
247 | ), |
||
248 | // Optional: Specify alternative variants of the library, if available.
|
||
249 | 'variants' => array( |
||
250 | // All properties defined for 'minified' override top-level properties.
|
||
251 | 'minified' => array( |
||
252 | 'files' => array( |
||
253 | 'js' => array( |
||
254 | 'exlib.min.js',
|
||
255 | 'gadgets/foo.min.js',
|
||
256 | ), |
||
257 | 'css' => array( |
||
258 | 'lib_style.css',
|
||
259 | 'skin/example.css',
|
||
260 | ), |
||
261 | ), |
||
262 | 'variant callback' => 'mymodule_check_variant', |
||
263 | 'variant arguments' => array( |
||
264 | 'variant' => 'minified', |
||
265 | ), |
||
266 | ), |
||
267 | ), |
||
268 | // Optional, but usually required: Override top-level properties for later
|
||
269 | // versions of the library. The properties of the minimum version that is
|
||
270 | // matched override the top-level properties. Note:
|
||
271 | // - When registering 'versions', it usually does not make sense to register
|
||
272 | // 'files', 'variants', and 'integration files' on the top-level, as most
|
||
273 | // of those likely need to be different per version and there are no
|
||
274 | // defaults.
|
||
275 | // - The array keys have to be strings, as PHP does not support floats for
|
||
276 | // array keys.
|
||
277 | 'versions' => array( |
||
278 | '2' => array( |
||
279 | 'files' => array( |
||
280 | 'js' => array('exlib.js'), |
||
281 | 'css' => array('exlib_style.css'), |
||
282 | ), |
||
283 | ), |
||
284 | '3.0' => array( |
||
285 | 'files' => array( |
||
286 | 'js' => array('exlib.js'), |
||
287 | 'css' => array('lib_style.css'), |
||
288 | ), |
||
289 | ), |
||
290 | '3.2' => array( |
||
291 | 'files' => array( |
||
292 | 'js' => array( |
||
293 | 'exlib.js',
|
||
294 | 'gadgets/foo.js',
|
||
295 | ), |
||
296 | 'css' => array( |
||
297 | 'lib_style.css',
|
||
298 | 'skin/example.css',
|
||
299 | ), |
||
300 | ), |
||
301 | ), |
||
302 | ), |
||
303 | // Optional: Register files to auto-load for your module. All files must be
|
||
304 | // keyed by module, and follow the syntax of the 'files' property.
|
||
305 | 'integration files' => array( |
||
306 | 'mymodule' => array( |
||
307 | 'js' => array('ex_lib.inc'), |
||
308 | ), |
||
309 | ), |
||
310 | // Optionally register callbacks to apply to the library during different
|
||
311 | // stages of its lifetime ('callback groups').
|
||
312 | 'callbacks' => array( |
||
313 | // Used to alter the info associated with the library.
|
||
314 | 'info' => array( |
||
315 | 'mymodule_example_libraries_info_callback',
|
||
316 | ), |
||
317 | // Called before detecting the given library.
|
||
318 | 'pre-detect' => array( |
||
319 | 'mymodule_example_libraries_predetect_callback',
|
||
320 | ), |
||
321 | // Called after detecting the library.
|
||
322 | 'post-detect' => array( |
||
323 | 'mymodule_example_libraries_postdetect_callback',
|
||
324 | ), |
||
325 | // Called before the library's dependencies are loaded.
|
||
326 | 3753f249 | Assos Assos | 'pre-dependencies-load' => array( |
327 | 85ad3d82 | Assos Assos | 'mymodule_example_libraries_pre_dependencies_load_callback',
|
328 | ), |
||
329 | // Called before the library is loaded.
|
||
330 | 'pre-load' => array( |
||
331 | 'mymodule_example_libraries_preload_callback',
|
||
332 | ), |
||
333 | // Called after the library is loaded.
|
||
334 | 'post-load' => array( |
||
335 | 'mymodule_example_libraries_postload_callback',
|
||
336 | ), |
||
337 | ), |
||
338 | ); |
||
339 | |||
340 | // A very simple library. No changing APIs (hence, no versions), no variants.
|
||
341 | // Expected to be extracted into 'sites/all/libraries/simple'.
|
||
342 | $libraries['simple'] = array( |
||
343 | 'name' => 'Simple library', |
||
344 | 'vendor url' => 'http://example.com/simple', |
||
345 | 'download url' => 'http://example.com/simple', |
||
346 | 'version arguments' => array( |
||
347 | 'file' => 'readme.txt', |
||
348 | // Best practice: Document the actual version strings for later reference.
|
||
349 | // 1.x: Version 1.0
|
||
350 | 'pattern' => '/Version (\d+)/', |
||
351 | 'lines' => 5, |
||
352 | ), |
||
353 | 'files' => array( |
||
354 | 'js' => array('simple.js'), |
||
355 | ), |
||
356 | ); |
||
357 | |||
358 | // A library that (naturally) evolves over time with API changes.
|
||
359 | $libraries['tinymce'] = array( |
||
360 | 'name' => 'TinyMCE', |
||
361 | 'vendor url' => 'http://tinymce.moxiecode.com', |
||
362 | 'download url' => 'http://tinymce.moxiecode.com/download.php', |
||
363 | 'path' => 'jscripts/tiny_mce', |
||
364 | // The regular expression catches two parts (the major and the minor
|
||
365 | // version), which libraries_get_version() doesn't allow.
|
||
366 | 'version callback' => 'tinymce_get_version', |
||
367 | 'version arguments' => array( |
||
368 | // It can be easier to parse the first characters of a minified file
|
||
369 | // instead of doing a multi-line pattern matching in a source file. See
|
||
370 | // 'lines' and 'cols' below.
|
||
371 | 'file' => 'jscripts/tiny_mce/tiny_mce.js', |
||
372 | // Best practice: Document the actual version strings for later reference.
|
||
373 | // 2.x: this.majorVersion="2";this.minorVersion="1.3"
|
||
374 | // 3.x: majorVersion:'3',minorVersion:'2.0.1'
|
||
375 | 'pattern' => '@majorVersion[=:]["\'](\d).+?minorVersion[=:]["\']([\d\.]+)@', |
||
376 | 'lines' => 1, |
||
377 | 'cols' => 100, |
||
378 | ), |
||
379 | 'versions' => array( |
||
380 | '2.1' => array( |
||
381 | 'files' => array( |
||
382 | 'js' => array('tiny_mce.js'), |
||
383 | ), |
||
384 | 'variants' => array( |
||
385 | 'source' => array( |
||
386 | 'files' => array( |
||
387 | 'js' => array('tiny_mce_src.js'), |
||
388 | ), |
||
389 | ), |
||
390 | ), |
||
391 | 'integration files' => array( |
||
392 | 'wysiwyg' => array( |
||
393 | 'js' => array('editors/js/tinymce-2.js'), |
||
394 | 'css' => array('editors/js/tinymce-2.css'), |
||
395 | ), |
||
396 | ), |
||
397 | ), |
||
398 | // Definition used if 3.1 or above is detected.
|
||
399 | '3.1' => array( |
||
400 | // Does not support JS aggregation.
|
||
401 | 'files' => array( |
||
402 | 'js' => array( |
||
403 | 'tiny_mce.js' => array('preprocess' => FALSE), |
||
404 | ), |
||
405 | ), |
||
406 | 'variants' => array( |
||
407 | // New variant leveraging jQuery. Not stable yet; therefore not the
|
||
408 | // default variant.
|
||
409 | 'jquery' => array( |
||
410 | 'files' => array( |
||
411 | 'js' => array( |
||
412 | 'tiny_mce_jquery.js' => array('preprocess' => FALSE), |
||
413 | ), |
||
414 | ), |
||
415 | ), |
||
416 | 'source' => array( |
||
417 | 'files' => array( |
||
418 | 'js' => array( |
||
419 | 'tiny_mce_src.js' => array('preprocess' => FALSE), |
||
420 | ), |
||
421 | ), |
||
422 | ), |
||
423 | ), |
||
424 | 'integration files' => array( |
||
425 | 'wysiwyg' => array( |
||
426 | 'js' => array('editors/js/tinymce-3.js'), |
||
427 | 'css' => array('editors/js/tinymce-3.css'), |
||
428 | ), |
||
429 | ), |
||
430 | ), |
||
431 | ), |
||
432 | ); |
||
433 | return $libraries; |
||
434 | } |
||
435 | |||
436 | /**
|
||
437 | * Alter the library information before detection and caching takes place.
|
||
438 | *
|
||
439 | * The library definitions are passed by reference. A common use-case is adding
|
||
440 | * a module's integration files to the library array, so that the files are
|
||
441 | * loaded whenever the library is. As noted above, it is important to declare
|
||
442 | * integration files inside of an array, whose key is the module name.
|
||
443 | *
|
||
444 | * @see hook_libraries_info()
|
||
445 | */
|
||
446 | function hook_libraries_info_alter(&$libraries) { |
||
447 | $files = array( |
||
448 | 'php' => array('example_module.php_spellchecker.inc'), |
||
449 | ); |
||
450 | $libraries['php_spellchecker']['integration files']['example_module'] = $files; |
||
451 | } |
||
452 | |||
453 | /**
|
||
454 | * Specify paths to look for library info files.
|
||
455 | *
|
||
456 | * Libraries API looks in the following directories for library info files by
|
||
457 | * default:
|
||
458 | * - libraries
|
||
459 | * - profiles/$profile/libraries
|
||
460 | * - sites/all/libraries
|
||
461 | * - sites/$site/libraries
|
||
462 | * This hook allows you to specify additional locations to look for library info
|
||
463 | * files. This should only be used for modules that declare many libraries.
|
||
464 | * Modules that only implement a few libraries should implement
|
||
465 | * hook_libraries_info().
|
||
466 | *
|
||
467 | * @return
|
||
468 | * An array of paths.
|
||
469 | */
|
||
470 | function hook_libraries_paths() { |
||
471 | // Taken from the Libraries test module, which needs to specify the path to
|
||
472 | // the test library.
|
||
473 | return array(drupal_get_path('module', 'libraries_test') . '/example'); |
||
474 | } |