Issue #958162: Add pre-detect callback group. *API CHANGE*
[project/libraries.git] / libraries.api.php
CommitLineData
41234e95 1<?php
41234e95 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:
d8145a2d 16 * - name: The official, human-readable name of the library.
41234e95 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.
d8145a2d
TS
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.
d8145a2d
TS
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 programatically.
dbb7c2d4 34 * - version callback: (optional) The name of a function that detects and
35 * returns the full version string of the library. The first argument is
36 * always $library, an array containing all library information as described
37 * here. There are two ways to declare the version callback's additional
38 * arguments, either as a single $options parameter or as multiple
39 * parameters, which correspond to the two ways to specify the argument
40 * values (see 'version arguments'). Defaults to libraries_get_version().
41234e95 41 * - version arguments: A list of arguments to pass to the version callback.
d033c260
TS
42 * Version arguments can be declared either as an associative array whose
43 * keys are the argument names or as an indexed array without specifying
44 * keys. If declared as an associative array, the arguments get passed to
45 * the version callback as a single $options parameter whose keys are the
46 * argument names (i.e. $options is identical to the specified array). If
47 * declared as an indexed array, the array values get passed to the version
48 * callback as seperate arguments in the order they were declared. The
49 * default version callback libraries_get_version() expects a single,
a483bb17 50 * associative array with named keys:
41234e95 51 * - file: The filename to parse for the version, relative to the library
52 * path. For example: 'docs/changelog.txt'.
53 * - pattern: A string containing a regular expression (PCRE) to match the
dbb7c2d4 54 * library version. For example: '@version\s+([0-9a-zA-Z\.-]+)@'.
a483bb17
TS
55 * - lines: (optional) The maximum number of lines to search the pattern in.
56 * Defaults to 20.
41234e95 57 * - cols: (optional) The maximum number of characters per line to take into
a483bb17
TS
58 * account. Defaults to 200. In case of minified or compressed files, this
59 * prevents reading the entire file into memory.
41234e95 60 * - files: An associative array of library files to load. Supported keys are:
61 * - js: A list of JavaScript files to load, using the same syntax as Drupal
62 * core's hook_library().
63 * - css: A list of CSS files to load, using the same syntax as Drupal
64 * core's hook_library().
65 * - php: A list of PHP files to load.
66 * - variants: (optional) An associative array of available library variants.
67 * For example, the top-level 'files' property may refer to a default
68 * variant that is compressed. If the library also ships with a minified and
69 * uncompressed/source variant, those can be defined here. Each key should
70 * describe the variant type, e.g. 'minified' or 'source'. Each value is an
71 * associative array of top-level properties that are entirely overridden by
a483bb17
TS
72 * the variant, most often just 'files'. Additionally, each variant can
73 * contain following properties:
dbb7c2d4 74 * - variant callback: (optional) The name of a function that detects the
75 * variant and returns TRUE or FALSE, depending on whether the variant is
76 * available or not. The first argument is always $library, an array
77 * containing all library information as described here. The second
78 * argument is always a string containing the variant name. There are two
79 * ways to declare the variant callback's additinal arguments, either as a
80 * single $options parameter or as multiple parameters, which correspond
81 * to the two ways to specify the argument values (see 'variant
82 * arguments'). If ommitted, the variant is expected to always be
83 * available.
a483bb17 84 * - variant arguments: A list of arguments to pass to the variant callback.
d033c260
TS
85 * Variant arguments can be declared either as an associative array whose
86 * keys are the argument names or as an indexed array without specifying
87 * keys. If declared as an associative array, the arguments get passed to
88 * the variant callback as a single $options parameter whose keys are the
89 * argument names (i.e. $options is identical to the specified array). If
90 * declared as an indexed array, the array values get passed to the
91 * variant callback as seperate arguments in the order they were declared.
dbb7c2d4 92 * Variants can be version-specific (see 'versions').
41234e95 93 * - versions: (optional) An associative array of supported library versions.
dbb7c2d4 94 * Naturally, libraries evolve over time and so do their APIs. In case a
95 * library changes between versions, different 'files' may need to be
41234e95 96 * loaded, different 'variants' may become available, or Drupal modules need
dbb7c2d4 97 * to load different integration files adapted to the new version. Each key
98 * is a version *string* (PHP does not support floats as keys). Each value
99 * is an associative array of top-level properties that are entirely
100 * overridden by the version.
41234e95 101 * - integration files: (optional) An associative array whose keys are module
102 * names and whose values are sets of files to load for the module, using
103 * the same notion as the top-level 'files' property. Each specified file
dbb7c2d4 104 * should contain the path to the file relative to the module it belongs to.
926327cc 105 * - callbacks: An associative array whose keys are callback groups and whose
106 * values are arrays of callbacks to apply to the library in that group.
107 * Each callback receives the following arguments:
108 * - $library: An array of library information belonging to the top-level
109 * library, a specific version, a specific variant or a specific variant
110 * of a specific version. Because library information such as the 'files'
111 * property (see above) can be declared in all these different locations
112 * of the library array, but a callback may have to act on all these
113 * different parts of the library, it is called recursively for each
114 * library with a certain part of the libraries array passed as $library
115 * each time.
116 * - $version: If the $library array belongs to a certain version (see
117 * above), a string containing the version. NULL, otherwise.
118 * - $variant: If the $library array belongs to a certain variant (see
119 * above), a string containing the variant name. NULL, otherwise.
120 * Valid callback groups are:
f455d71f
TS
121 * - info: Callbacks registered in this group are applied after the library
122 * information has been retrieved via hook_libraries_info() or info files.
123 * - pre-detect: Callbacks registered in this group are applied after the
124 * library path has been determined and before the version callback is
125 * invoked. At this point the following additional information is available:
126 * - $library['library path']: The path on the file system to the library.
127 * - post-detect: Callbacks registered in this group are applied after the
128 * library has been successfully detected. At this point the library
926327cc 129 * contains the version-specific information, if specified, and following
130 * additional information is available:
131 * - $library['installed']: A boolean indicating whether the library is
132 * installed or not.
133 * - $library['version']: If it could be detected, a string containing the
134 * version of the library.
135 * - $library['variants'][$variant]['installed']: For each specified
136 * variant, a boolean indicating whether the variant is installed or
137 * not.
138 * Note that in this group the 'versions' property is no longer available.
139 * - load: Callbacks registered in this group are applied directly
140 * before this library is loaded. At this point the library contains
141 * variant-specific information, if specified. Note that in this group the
142 * 'variants' property is no longer available.
41234e95 143 * Additional top-level properties can be registered as needed.
a483bb17
TS
144 *
145 * @see hook_library()
41234e95 146 */
147function hook_libraries_info() {
148 // The following is a full explanation of all properties. See below for more
149 // concrete example implementations.
150
151 // This array key lets Libraries API search for 'sites/all/libraries/example'
152 // directory, which should contain the entire, original extracted library.
153 $libraries['example'] = array(
154 // Only used in administrative UI of Libraries API.
cb49c8ed 155 'name' => 'Example library',
41234e95 156 'vendor url' => 'http://example.com',
157 'download url' => 'http://example.com/download',
158 // Optional: If, after extraction, the actual library files are contained in
159 // 'sites/all/libraries/example/lib', specify the relative path here.
160 'path' => 'lib',
161 // Optional: Define a custom version detection callback, if required.
162 'version callback' => 'mymodule_get_version',
163 // Specify arguments for the version callback. By default,
164 // libraries_get_version() takes a named argument array:
165 'version arguments' => array(
166 'file' => 'docs/CHANGELOG.txt',
dbb7c2d4 167 'pattern' => '@version\s+([0-9a-zA-Z\.-]+)@',
41234e95 168 'lines' => 5,
169 'cols' => 20,
170 ),
171 // Default list of files of the library to load. Important: Only specify
172 // third-party files belonging to the library here, not integration files of
173 // your module.
174 'files' => array(
175 // 'js' and 'css' follow the syntax of hook_library(), but file paths are
176 // relative to the library path.
177 'js' => array(
178 'exlib.js',
179 'gadgets/foo.js',
180 ),
181 'css' => array(
182 'lib_style.css',
183 'skin/example.css',
184 ),
185 // For PHP libraries, specify include files here, still relative to the
186 // library path.
187 'php' => array(
188 'exlib.php',
189 'exlib.inc',
190 ),
191 ),
192 // Optional: Specify alternative variants of the library, if available.
193 'variants' => array(
194 // All properties defined for 'minified' override top-level properties.
195 'minified' => array(
196 'files' => array(
197 'js' => array(
198 'exlib.min.js',
199 'gadgets/foo.min.js',
200 ),
201 'css' => array(
202 'lib_style.css',
203 'skin/example.css',
204 ),
205 ),
a483bb17
TS
206 'variant callback' => 'mymodule_check_variant',
207 'variant arguments' => array(
208 'variant' => 'minified',
209 ),
41234e95 210 ),
211 ),
212 // Optional, but usually required: Override top-level properties for later
213 // versions of the library. The properties of the minimum version that is
214 // matched override the top-level properties. Note:
215 // - When registering 'versions', it usually does not make sense to register
216 // 'files', 'variants', and 'integration files' on the top-level, as most
217 // of those likely need to be different per version and there are no
218 // defaults.
219 // - The array keys have to be strings, as PHP does not support floats for
220 // array keys.
221 'versions' => array(
222 '2' => array(
223 'files' => array(
dbb7c2d4 224 'js' => array('exlib.js'),
225 'css' => array('exlib_style.css'),
41234e95 226 ),
227 ),
228 '3.0' => array(
229 'files' => array(
dbb7c2d4 230 'js' => array('exlib.js'),
231 'css' => array('lib_style.css'),
41234e95 232 ),
233 ),
234 '3.2' => array(
235 'files' => array(
236 'js' => array(
237 'exlib.js',
238 'gadgets/foo.js',
239 ),
240 'css' => array(
241 'lib_style.css',
242 'skin/example.css',
243 ),
244 ),
245 ),
246 ),
247 // Optional: Register files to auto-load for your module. All files must be
248 // keyed by module, and follow the syntax of the 'files' property.
249 'integration files' => array(
250 'mymodule' => array(
dbb7c2d4 251 'js' => array('ex_lib.inc'),
41234e95 252 ),
253 ),
926327cc 254 // Optionally register callbacks to apply to the library during different
255 // stages of its lifetime ('callback groups'). Here, a callback is
256 // registered in the 'detect' group.
257 'callbacks' => array(
258 'detect' => array(
259 'mymodule_example_detect_callback',
260 ),
261 ),
41234e95 262 );
263
264 // A very simple library. No changing APIs (hence, no versions), no variants.
265 // Expected to be extracted into 'sites/all/libraries/simple'.
266 $libraries['simple'] = array(
cb49c8ed 267 'name' => 'Simple library',
41234e95 268 'vendor url' => 'http://example.com/simple',
269 'download url' => 'http://example.com/simple',
270 'version arguments' => array(
271 'file' => 'readme.txt',
272 // Best practice: Document the actual version strings for later reference.
273 // 1.x: Version 1.0
dbb7c2d4 274 'pattern' => '/Version (\d+)/',
41234e95 275 'lines' => 5,
276 ),
277 'files' => array(
dbb7c2d4 278 'js' => array('simple.js'),
41234e95 279 ),
280 );
281
282 // A library that (naturally) evolves over time with API changes.
283 $libraries['tinymce'] = array(
cb49c8ed 284 'name' => 'TinyMCE',
41234e95 285 'vendor url' => 'http://tinymce.moxiecode.com',
286 'download url' => 'http://tinymce.moxiecode.com/download.php',
287 'path' => 'jscripts/tiny_mce',
dbb7c2d4 288 // The regular expression catches two parts (the major and the minor
289 // version), which libraries_get_version() doesn't allow.
290 'version callback' => 'tinymce_get_version',
41234e95 291 'version arguments' => array(
a483bb17
TS
292 // It can be easier to parse the first characters of a minified file
293 // instead of doing a multi-line pattern matching in a source file. See
294 // 'lines' and 'cols' below.
41234e95 295 'file' => 'jscripts/tiny_mce/tiny_mce.js',
296 // Best practice: Document the actual version strings for later reference.
297 // 2.x: this.majorVersion="2";this.minorVersion="1.3"
298 // 3.x: majorVersion:'3',minorVersion:'2.0.1'
299 'pattern' => '@majorVersion[=:]["\'](\d).+?minorVersion[=:]["\']([\d\.]+)@',
300 'lines' => 1,
301 'cols' => 100,
302 ),
303 'versions' => array(
304 '2.1' => array(
305 'files' => array(
306 'js' => array('tiny_mce.js'),
307 ),
308 'variants' => array(
309 'source' => array(
310 'files' => array(
311 'js' => array('tiny_mce_src.js'),
312 ),
313 ),
314 ),
315 'integration files' => array(
316 'wysiwyg' => array(
dbb7c2d4 317 'js' => array('editors/js/tinymce-2.js'),
318 'css' => array('editors/js/tinymce-2.css'),
41234e95 319 ),
320 ),
321 ),
322 // Definition used if 3.1 or above is detected.
323 '3.1' => array(
324 // Does not support JS aggregation.
325 'files' => array(
326 'js' => array(
327 'tiny_mce.js' => array('preprocess' => FALSE),
328 ),
329 ),
330 'variants' => array(
331 // New variant leveraging jQuery. Not stable yet; therefore not the
332 // default variant.
333 'jquery' => array(
334 'files' => array(
335 'js' => array(
336 'tiny_mce_jquery.js' => array('preprocess' => FALSE),
337 ),
338 ),
339 ),
340 'source' => array(
341 'files' => array(
342 'js' => array(
343 'tiny_mce_src.js' => array('preprocess' => FALSE),
344 ),
345 ),
346 ),
347 ),
348 'integration files' => array(
349 'wysiwyg' => array(
dbb7c2d4 350 'js' => array('editors/js/tinymce-3.js'),
351 'css' => array('editors/js/tinymce-3.css'),
41234e95 352 ),
353 ),
354 ),
355 ),
356 );
357 return $libraries;
358}
a483bb17
TS
359
360/**
361 * Alter the library information before detection and caching takes place.
362 *
363 * The library definitions are passed by reference. A common use-case is adding
364 * a module's integration files to the library array, so that the files are
365 * loaded whenever the library is. As noted above, it is important to declare
366 * integration files inside of an array, whose key is the module name.
367 *
368 * @see hook_libraries_info()
369 */
370function hook_libraries_info_alter(&$libraries) {
371 $files = array(
372 'php' => array('example_module.php_spellchecker.inc'),
373 );
374 $libraries['php_spellchecker']['integration files']['example_module'] = $files;
375}
c365e82b
TS
376
377/**
378 * Specify paths to look for library info files.
379 *
380 * Libraries API looks in the following directories for library info files by
381 * default:
382 * - libraries
383 * - profiles/$profile/libraries
384 * - sites/all/libraries
385 * - sites/$site/libraries
386 * This hook allows you to specify additional locations to look for library info
387 * files. This should only be used for modules that declare many libraries.
388 * Modules that only implement a few libraries should implement
389 * hook_libraries_info().
390 *
391 * @return
392 * An array of paths.
393 */
394function hook_libraries_paths() {
395 // Taken from the Libraries test module, which needs to specify the path to
396 // the test library.
397 return array(drupal_get_path('module', 'libraries_test') . '/example');
398}