487 lines
23 KiB
PHP
487 lines
23 KiB
PHP
<?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.
|
|
* For libraries that provide a package.json file, use
|
|
* 'libraries_get_package_json_version' as the version callback.
|
|
* - 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');
|
|
}
|