<?php /** * @file * Documents API functions for Libraries module. */ /** * Return information about external libraries. * * @return * An associative array whose keys are internal names of libraries and whose * values are describing each library. Each key is the directory name below * the 'libraries' directory, in which the library may be found. Each value is * an associative array containing: * - name: The official, human-readable name of the library. * - vendor url: The URL of the homepage of the library. * - download url: The URL of a web page on which the library can be obtained. * - download file url: (optional) The URL where the latest version of the * library can be downloaded. In case such a static URL exists the library * can be downloaded automatically via Drush. Run * 'drush help libraries-download' in the command-line for more information. * - path: (optional) A relative path from the directory of the library to the * actual library. Only required if the extracted download package contains * the actual library files in a sub-directory. * - library path: (optional) The absolute path to the library directory. This * should not be declared normally, as it is automatically detected, to * allow for multiple possible library locations. A valid use-case is an * external library, in which case the full URL to the library should be * specified here. * - version: (optional) The version of the library. This should not be * declared normally, as it is automatically detected (see 'version * callback' below) to allow for version changes of libraries without code * changes of implementing modules and to support different versions of a * library simultaneously (though only one version can be installed per * site). A valid use-case is an external library whose version cannot be * determined programmatically. Either 'version' or 'version callback' (or * 'version arguments' in case libraries_get_version() is being used as a * version callback) must be declared. * - version callback: (optional) The name of a function that detects and * returns the full version string of the library. The first argument is * always $library, an array containing all library information as described * here. There are two ways to declare the version callback's additional * arguments, either as a single $options parameter or as multiple * parameters, which correspond to the two ways to specify the argument * values (see 'version arguments'). Defaults to libraries_get_version(). * Unless 'version' is declared or libraries_get_version() is being used as * a version callback, 'version callback' must be declared. In the latter * case, however, 'version arguments' must be declared in the specified way. * - version arguments: (optional) A list of arguments to pass to the version * callback. Version arguments can be declared either as an associative * array whose keys are the argument names or as an indexed array without * specifying keys. If declared as an associative array, the arguments get * passed to the version callback as a single $options parameter whose keys * are the argument names (i.e. $options is identical to the specified * array). If declared as an indexed array, the array values get passed to * the version callback as separate arguments in the order they were * declared. The default version callback libraries_get_version() expects a * single, associative array with named keys: * - file: The filename to parse for the version, relative to the path * speficied as the 'library path' property (see above). For example: * 'docs/changelog.txt'. * - pattern: A string containing a regular expression (PCRE) to match the * library version. For example: '@version\s+([0-9a-zA-Z\.-]+)@'. Note * that the returned version is not the match of the entire pattern (i.e. * '@version 1.2.3' in the above example) but the match of the first * sub-pattern (i.e. '1.2.3' in the above example). * - lines: (optional) The maximum number of lines to search the pattern in. * Defaults to 20. * - cols: (optional) The maximum number of characters per line to take into * account. Defaults to 200. In case of minified or compressed files, this * prevents reading the entire file into memory. * Defaults to an empty array. 'version arguments' must be specified unless * 'version' is declared or the specified 'version callback' does not * require any arguments. The latter might be the case with a * library-specific version callback, for example. * - files: An associative array of library files to load. Supported keys are: * - js: A list of JavaScript files to load, using the same syntax as Drupal * core's hook_library(). * - css: A list of CSS files to load, using the same syntax as Drupal * core's hook_library(). * - php: A list of PHP files to load. * - dependencies: An array of libraries this library depends on. Similar to * declaring module dependencies, the dependency declaration may contain * information on the supported version. Examples of supported declarations: * @code * $libraries['dependencies'] = array( * // Load the 'example' library, regardless of the version available: * 'example', * // Only load the 'example' library, if version 1.2 is available: * 'example (1.2)', * // Only load a version later than 1.3-beta2 of the 'example' library: * 'example (>1.3-beta2)' * // Only load a version equal to or later than 1.3-beta3: * 'example (>=1.3-beta3)', * // Only load a version earlier than 1.5: * 'example (<1.5)', * // Only load a version equal to or earlier than 1.4: * 'example (<=1.4)', * // Combinations of the above are allowed as well: * 'example (>=1.3-beta2, <1.5)', * ); * @endcode * - variants: (optional) An associative array of available library variants. * For example, the top-level 'files' property may refer to a default * variant that is compressed. If the library also ships with a minified and * uncompressed/source variant, those can be defined here. Each key should * describe the variant type, e.g. 'minified' or 'source'. Each value is an * associative array of top-level properties that are entirely overridden by * the variant, most often just 'files'. Additionally, each variant can * contain following properties: * - variant callback: (optional) The name of a function that detects the * variant and returns TRUE or FALSE, depending on whether the variant is * available or not. The first argument is always $library, an array * containing all library information as described here. The second * argument is always a string containing the variant name. There are two * ways to declare the variant callback's additional arguments, either as a * single $options parameter or as multiple parameters, which correspond * to the two ways to specify the argument values (see 'variant * arguments'). If omitted, the variant is expected to always be * available. * - variant arguments: A list of arguments to pass to the variant callback. * Variant arguments can be declared either as an associative array whose * keys are the argument names or as an indexed array without specifying * keys. If declared as an associative array, the arguments get passed to * the variant callback as a single $options parameter whose keys are the * argument names (i.e. $options is identical to the specified array). If * declared as an indexed array, the array values get passed to the * variant callback as separate arguments in the order they were declared. * Variants can be version-specific (see 'versions'). * - versions: (optional) An associative array of supported library versions. * Naturally, libraries evolve over time and so do their APIs. In case a * library changes between versions, different 'files' may need to be * loaded, different 'variants' may become available, or Drupal modules need * to load different integration files adapted to the new version. Each key * is a version *string* (PHP does not support floats as keys). Each value * is an associative array of top-level properties that are entirely * overridden by the version. * - integration files: (optional) An associative array whose keys are module * names and whose values are sets of files to load for the module, using * the same notion as the top-level 'files' property. Each specified file * should contain the path to the file relative to the module it belongs to. * - callbacks: An associative array whose keys are callback groups and whose * values are arrays of callbacks to apply to the library in that group. * Each callback receives the following arguments: * - $library: An array of library information belonging to the top-level * library, a specific version, a specific variant or a specific variant * of a specific version. Because library information such as the 'files' * property (see above) can be declared in all these different locations * of the library array, but a callback may have to act on all these * different parts of the library, it is called recursively for each * library with a certain part of the libraries array passed as $library * each time. * - $version: If the $library array belongs to a certain version (see * above), a string containing the version. This argument may be empty, so * NULL should be specified as the default value. * - $variant: If the $library array belongs to a certain variant (see * above), a string containing the variant name. This argument may be * empty, so NULL should be specified as the default value. * Valid callback groups are: * - info: Callbacks registered in this group are applied after the library * information has been retrieved via hook_libraries_info() or info files. * At this point the following additional information is available: * - $library['info type']: How the library information was obtained. Can * be 'info file', 'module', or 'theme', depending on whether the * library information was obtained from an info file, an enabled module * or an enabled theme, respectively. * Additionally, one of the following three keys is available, depending * on the value of $library['info type']. * - $library['info file']: In case the library information was obtained * from an info file, the URI of the info file. * - $library['module']: In case the library was obtained from an enabled * module, the name of the providing module. * - $library['theme']: In case the library was obtained from an enabled * theme, the name of the providing theme. * - pre-detect: Callbacks registered in this group are applied after the * library path has been determined and before the version callback is * invoked. At this point the following additional information is * available: * - $library['library path']: The path on the file system to the library. * - post-detect: Callbacks registered in this group are applied after the * library has been successfully detected. At this point the library * contains the version-specific information, if specified, and following * additional information is available: * - $library['installed']: A boolean indicating whether the library is * installed or not. * - $library['version']: If it could be detected, a string containing the * version of the library. * - $library['variants'][$variant]['installed']: For each specified * variant, a boolean indicating whether the variant is installed or * not. * Note that in this group the 'versions' property is no longer available. * - pre-dependencies-load: Callbacks registered in this group are applied * directly before the library's dependencies are loaded. At this point * the library contains variant-specific information, if specified. Note * that in this group the 'variants' property is no longer available. * - pre-load: Callbacks registered in this group are applied directly after * the library's dependencies are loaded and before the library itself is * loaded. * - post-load: Callbacks registered in this group are applied directly * after this library is loaded. At this point, the library contains a * 'loaded' key, which contains the number of files that were loaded. * Additional top-level properties can be registered as needed. * * @see hook_library() */ function hook_libraries_info() { // The following is a full explanation of all properties. See below for more // concrete example implementations. // This array key lets Libraries API search for 'sites/all/libraries/example' // directory, which should contain the entire, original extracted library. $libraries['example'] = array( // Only used in administrative UI of Libraries API. 'name' => 'Example library', 'vendor url' => 'http://example.com', 'download url' => 'http://example.com/download', // It is important that this URL does not include the actual version to // download. Not all libraries provide such a static URL. 'download file url' => 'http://example.com/latest.tar.gz', // Optional: If, after extraction, the actual library files are contained in // 'sites/all/libraries/example/lib', specify the relative path here. 'path' => 'lib', // Optional: Define a custom version detection callback, if required. 'version callback' => 'mymodule_get_version', // Specify arguments for the version callback. By default, // libraries_get_version() takes a named argument array: 'version arguments' => array( 'file' => 'docs/CHANGELOG.txt', 'pattern' => '@version\s+([0-9a-zA-Z\.-]+)@', 'lines' => 5, 'cols' => 20, ), // Default list of files of the library to load. Important: Only specify // third-party files belonging to the library here, not integration files of // your module. 'files' => array( // 'js' and 'css' follow the syntax of hook_library(), but file paths are // relative to the library path. 'js' => array( 'exlib.js', 'gadgets/foo.js', ), 'css' => array( 'lib_style.css', 'skin/example.css', ), // For PHP libraries, specify include files here, still relative to the // library path. 'php' => array( 'exlib.php', 'exlib.inc', ), ), // Optional: Specify alternative variants of the library, if available. 'variants' => array( // All properties defined for 'minified' override top-level properties. 'minified' => array( 'files' => array( 'js' => array( 'exlib.min.js', 'gadgets/foo.min.js', ), 'css' => array( 'lib_style.css', 'skin/example.css', ), ), 'variant callback' => 'mymodule_check_variant', 'variant arguments' => array( 'variant' => 'minified', ), ), ), // Optional, but usually required: Override top-level properties for later // versions of the library. The properties of the minimum version that is // matched override the top-level properties. Note: // - When registering 'versions', it usually does not make sense to register // 'files', 'variants', and 'integration files' on the top-level, as most // of those likely need to be different per version and there are no // defaults. // - The array keys have to be strings, as PHP does not support floats for // array keys. 'versions' => array( '2' => array( 'files' => array( 'js' => array('exlib.js'), 'css' => array('exlib_style.css'), ), ), '3.0' => array( 'files' => array( 'js' => array('exlib.js'), 'css' => array('lib_style.css'), ), ), '3.2' => array( 'files' => array( 'js' => array( 'exlib.js', 'gadgets/foo.js', ), 'css' => array( 'lib_style.css', 'skin/example.css', ), ), ), ), // Optional: Register files to auto-load for your module. All files must be // keyed by module, and follow the syntax of the 'files' property. 'integration files' => array( 'mymodule' => array( 'js' => array('ex_lib.inc'), ), ), // Optionally register callbacks to apply to the library during different // stages of its lifetime ('callback groups'). 'callbacks' => array( // Used to alter the info associated with the library. 'info' => array( 'mymodule_example_libraries_info_callback', ), // Called before detecting the given library. 'pre-detect' => array( 'mymodule_example_libraries_predetect_callback', ), // Called after detecting the library. 'post-detect' => array( 'mymodule_example_libraries_postdetect_callback', ), // Called before the library's dependencies are loaded. 'pre-dependencies-load' => array( 'mymodule_example_libraries_pre_dependencies_load_callback', ), // Called before the library is loaded. 'pre-load' => array( 'mymodule_example_libraries_preload_callback', ), // Called after the library is loaded. 'post-load' => array( 'mymodule_example_libraries_postload_callback', ), ), ); // A very simple library. No changing APIs (hence, no versions), no variants. // Expected to be extracted into 'sites/all/libraries/simple'. $libraries['simple'] = array( 'name' => 'Simple library', 'vendor url' => 'http://example.com/simple', 'download url' => 'http://example.com/simple', // The download file URL can also point to a single file (instead of an // archive). 'download file url' => 'http://example.com/latest/simple.js', 'version arguments' => array( 'file' => 'readme.txt', // Best practice: Document the actual version strings for later reference. // 1.x: Version 1.0 'pattern' => '/Version (\d+)/', 'lines' => 5, ), 'files' => array( 'js' => array('simple.js'), ), ); // A library that (naturally) evolves over time with API changes. $libraries['tinymce'] = array( 'name' => 'TinyMCE', 'vendor url' => 'http://tinymce.moxiecode.com', 'download url' => 'http://tinymce.moxiecode.com/download.php', 'path' => 'jscripts/tiny_mce', // The regular expression catches two parts (the major and the minor // version), which libraries_get_version() doesn't allow. 'version callback' => 'tinymce_get_version', 'version arguments' => array( // It can be easier to parse the first characters of a minified file // instead of doing a multi-line pattern matching in a source file. See // 'lines' and 'cols' below. 'file' => 'jscripts/tiny_mce/tiny_mce.js', // Best practice: Document the actual version strings for later reference. // 2.x: this.majorVersion="2";this.minorVersion="1.3" // 3.x: majorVersion:'3',minorVersion:'2.0.1' 'pattern' => '@majorVersion[=:]["\'](\d).+?minorVersion[=:]["\']([\d\.]+)@', 'lines' => 1, 'cols' => 100, ), 'versions' => array( '2.1' => array( 'files' => array( 'js' => array('tiny_mce.js'), ), 'variants' => array( 'source' => array( 'files' => array( 'js' => array('tiny_mce_src.js'), ), ), ), 'integration files' => array( 'wysiwyg' => array( 'js' => array('editors/js/tinymce-2.js'), 'css' => array('editors/js/tinymce-2.css'), ), ), ), // Definition used if 3.1 or above is detected. '3.1' => array( // Does not support JS aggregation. 'files' => array( 'js' => array( 'tiny_mce.js' => array('preprocess' => FALSE), ), ), 'variants' => array( // New variant leveraging jQuery. Not stable yet; therefore not the // default variant. 'jquery' => array( 'files' => array( 'js' => array( 'tiny_mce_jquery.js' => array('preprocess' => FALSE), ), ), ), 'source' => array( 'files' => array( 'js' => array( 'tiny_mce_src.js' => array('preprocess' => FALSE), ), ), ), ), 'integration files' => array( 'wysiwyg' => array( 'js' => array('editors/js/tinymce-3.js'), 'css' => array('editors/js/tinymce-3.css'), ), ), ), ), ); return $libraries; } /** * Alter the library information before detection and caching takes place. * * The library definitions are passed by reference. A common use-case is adding * a module's integration files to the library array, so that the files are * loaded whenever the library is. As noted above, it is important to declare * integration files inside of an array, whose key is the module name. * * @see hook_libraries_info() */ function hook_libraries_info_alter(&$libraries) { $files = array( 'php' => array('example_module.php_spellchecker.inc'), ); $libraries['php_spellchecker']['integration files']['example_module'] = $files; } /** * Specify paths to look for library info files. * * Libraries API looks in the following directories for library info files by * default: * - libraries * - profiles/$profile/libraries * - sites/all/libraries * - sites/$site/libraries * This hook allows you to specify additional locations to look for library info * files. This should only be used for modules that declare many libraries. * Modules that only implement a few libraries should implement * hook_libraries_info(). * * @return * An array of paths. */ function hook_libraries_info_file_paths() { // Taken from the Libraries test module, which needs to specify the path to // the test library. return array(drupal_get_path('module', 'libraries_test') . '/example'); }