1<?php 2 3/** 4 * @file 5 * Provides information about external libraries. 6 */ 7 8 9/** 10 * Class PLUGIN_library. 11 */ 12class gallery_library 13{ 14 15 /** 16 * Return information about external libraries. 17 * 18 * @return 19 * An associative array whose keys are internal names of libraries and whose values are describing each library. 20 * Each key is the directory name below the '{e_WEB}/lib' directory, in which the library may be found. Each 21 * value is an associative array containing: 22 * - name: The official, human-readable name of the library. 23 * - vendor_url: The URL of the homepage of the library. 24 * - download_url: The URL of a web page on which the library can be obtained. 25 * - path: (optional) A relative path from the directory of the library to the actual library. Only required if 26 * the extracted download package contains the actual library files in a sub-directory. 27 * - library_path: (optional) The absolute path to the library directory. This should not be declared normally, as 28 * it is automatically detected, to allow for multiple possible library locations. A valid use-case is an 29 * external library, in which case the full URL to the library should be specified here. 30 * - version: (optional) The version of the library. This should not be declared normally, as it is automatically 31 * detected (see 'version_callback' below) to allow for version changes of libraries without code changes of 32 * implementing plugins and to support different versions of a library simultaneously. A valid use-case is an 33 * external library whose version cannot be determined programmatically. Either 'version' or 'version_callback' 34 * (or 'version_arguments' in case libraryGetVersion() is being used as a version callback) must be declared. 35 * - version_callback: (optional) The name of a function that detects and returns the full version string of the 36 * library. The first argument is always $library, an array containing all library information as described here. 37 * There are two ways to declare the version callback's additional arguments, either as a single $options 38 * parameter or as multiple parameters, which correspond to the two ways to specify the argument values (see 39 * 'version_arguments'). Defaults to libraryGetVersion(). Unless 'version' is declared or libraryGetVersion() 40 * is being used as a version callback, 'version_callback' must be declared. In the latter case, however, 41 * 'version_arguments' must be declared in the specified way. 42 * - version_arguments: (optional) A list of arguments to pass to the version callback. Version arguments can be 43 * declared either as an associative array whose keys are the argument names or as an indexed array without 44 * specifying keys. If declared as an associative array, the arguments get passed to the version callback as a 45 * single $options parameter whose keys are the argument names (i.e. $options is identical to the specified 46 * array). If declared as an indexed array, the array values get passed to the version callback as separate 47 * arguments in the order they were declared. The default version callback libraryGetVersion() expects a 48 * single, associative array with named keys: 49 * - file: The filename to parse for the version, relative to the path specified as the 'library_path' property 50 * (see above). For example: 'docs/changelog.txt'. 51 * - pattern: A string containing a regular expression (PCRE) to match the library version. For example: 52 * '@version\s+([0-9a-zA-Z\.-]+)@'. Note that the returned version is not the match of the entire pattern 53 * (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 54 * above example). 55 * - lines: (optional) The maximum number of lines to search the pattern in. Defaults to 20. 56 * - cols: (optional) The maximum number of characters per line to take into account. Defaults to 200. In case 57 * of minified or compressed files, this prevents reading the entire file into memory. 58 * Defaults to an empty array. 'version_arguments' must be specified unless 'version' is declared or the 59 * specified 'version_callback' does not require any arguments. The latter might be the case with a 60 * library-specific version callback, for example. 61 * - files: An associative array of library files to load. Supported keys are: 62 * - js: A list of JavaScript files to load. 63 * - css: A list of CSS files to load. 64 * - php: A list of PHP files to load. 65 * - dependencies: An array of libraries this library depends on. Similar to declaring plugin dependencies, the 66 * dependency declaration may contain information on the supported version. Examples of supported declarations: 67 * @code 68 * $library['dependencies'] = array( 69 * // Load the 'example' library, regardless of the version available: 70 * 'example', 71 * // Only load the 'example' library, if version 1.2 is available: 72 * 'example (1.2)', 73 * // Only load a version later than 1.3-beta2 of the 'example' library: 74 * 'example (>1.3-beta2)' 75 * // Only load a version equal to or later than 1.3-beta3: 76 * 'example (>=1.3-beta3)', 77 * // Only load a version earlier than 1.5: 78 * 'example (<1.5)', 79 * // Only load a version equal to or earlier than 1.4: 80 * 'example (<=1.4)', 81 * // Combinations of the above are allowed as well: 82 * 'example (>=1.3-beta2, <1.5)', 83 * ); 84 * @endcode 85 * - variants: (optional) An associative array of available library variants. For example, the top-level 'files' 86 * property may refer to a default variant that is compressed. If the library also ships with a minified and 87 * uncompressed/source variant, those can be defined here. Each key should describe the variant type, e.g. 88 * 'minified' or 'source'. Each value is an associative array of top-level properties that are entirely 89 * overridden by the variant, most often just 'files'. Additionally, each variant can contain following 90 * properties: 91 * - variant_callback: (optional) The name of a function that detects the variant and returns TRUE or FALSE, 92 * depending on whether the variant is available or not. The first argument is always $library, an array 93 * containing all library information as described here. The second argument is always a string containing the 94 * variant name. There are two ways to declare the variant callback's additional arguments, either as a single 95 * $options parameter or as multiple parameters, which correspond to the two ways to specify the argument 96 * values (see 'variant_arguments'). If omitted, the variant is expected to always be available. 97 * - variant_arguments: A list of arguments to pass to the variant callback. Variant arguments can be declared 98 * either as an associative array whose keys are the argument names or as an indexed array without specifying 99 * keys. If declared as an associative array, the arguments get passed to the variant callback as a single 100 * $options parameter whose keys are the argument names (i.e. $options is identical to the specified array). 101 * If declared as an indexed array, the array values get passed to the variant callback as separate arguments 102 * in the order they were declared. 103 * Variants can be version-specific (see 'versions'). 104 * - versions: (optional) An associative array of supported library versions. Naturally, libraries evolve over 105 * time and so do their APIs. In case a library changes between versions, different 'files' may need to be 106 * loaded, different 'variants' may become available, or e107 plugins need to load different integration files 107 * adapted to the new version. Each key is a version *string* (PHP does not support floats as keys). Each value 108 * is an associative array of top-level properties that are entirely overridden by the version. 109 * - integration_files: (optional) Sets of files to load for the plugin, using the same notion as the top-level 110 * 'files' property. Each specified file should contain the path to the file relative to the plugin it belongs 111 * to. 112 * Additional top-level properties can be registered as needed. 113 */ 114 function config() 115 { 116 $libraries['jquery.prettyPhoto'] = array( 117 // Only used in administrative UI of Libraries API. 118 'name' => 'prettyPhoto', 119 'vendor_url' => 'http://www.no-margin-for-errors.com', 120 'download_url' => 'https://github.com/scaron/prettyphoto', 121 'version_arguments' => array( 122 'file' => 'js/jquery.prettyPhoto.js', 123 // Version: 3.1.6 124 'pattern' => '/Version: (\d+\.+\d+\.+\d+)/', 125 'lines' => 5, 126 ), 127 'files' => array( 128 'js' => array( 129 'js/jquery.prettyPhoto.js' => array( 130 'type' => 'footer', 131 ), 132 ), 133 'css' => array( 134 'css/prettyPhoto.css', 135 ), 136 ), 137 ); 138 139 $libraries['jquery.cycle'] = array( 140 // Only used in administrative UI of Libraries API. 141 'name' => 'jQuery Cycle Plugin', 142 'vendor_url' => 'http://jquery.malsup.com/cycle/', 143 'download_url' => 'http://jquery.malsup.com/cycle/', 144 'version_arguments' => array( 145 'file' => 'jquery.cycle.all.js', 146 // Version: 2.9999.5 147 'pattern' => '/Version: (\d+\.+\d+\.+\d+)/', 148 'lines' => 5, 149 ), 150 'files' => array( 151 'js' => array( 152 'jquery.cycle.all.js' => array( 153 'type' => 'footer', 154 ), 155 ), 156 ), 157 ); 158 159 return $libraries; 160 } 161 162} 163