Change the version back to dev.
[project/libraries.git] / libraries.api.php
1 <?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 * 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 * - 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 * 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 * - 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 * 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 * - 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 * ways to declare the variant callback's additional arguments, either as a
114 * single $options parameter or as multiple parameters, which correspond
115 * to the two ways to specify the argument values (see 'variant
116 * arguments'). If omitted, the variant is expected to always be
117 * 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 * variant callback as separate arguments in the order they were declared.
126 * 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 * 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 * - pre-detect: Callbacks registered in this group are applied after the
173 * library path has been determined and before the version callback is
174 * invoked. At this point the following additional information is
175 * available:
176 * - $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 'pre-dependencies-load' => array(
327 '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 }