#958162 by tstoeckler, sun: Code clean-up, tests revamp, more robust loading.

CHANGELOG.txt

@@ -6,6 +6,7 @@ Libraries x.x-x.x, xxxx-xx-xx
 
 Libraries 7.x-1.x, xxxx-xx-xx
 -----------------------------
+#958162 by tstoeckler, sun: Code clean-up, tests revamp, more robust loading.
 #919632 by tstoeckler, sun: Allow library information to be stored in info files.
 by sun: Fixed testbot breaks upon directory name/info file name mismatch.
 #864376 by tstoeckler, sun: Code-cleanup, allow hard-coded 'version'.

libraries.api.php

@@ -14,12 +14,17 @@
  *   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:
- *   - title: The official, human-readable name of the library.
+ *   - 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.
  *   - 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 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
@@ -27,6 +32,13 @@
  *     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().
+ *   - 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 programatically.
  *   - version arguments: 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

libraries.module

@@ -182,14 +182,15 @@ function libraries_info($library = NULL) {
 
   if (!isset($libraries)) {
     $libraries = array();
+    // Gather information from hook_libraries_info().
     foreach (module_implements('libraries_info') as $module) {
       foreach (module_invoke($module, 'libraries_info') as $name => $properties) {
         $properties['module'] = $module;
-        $properties['name'] = $name;
         $libraries[$name] = $properties;
       }
     }
     // Gather information from .info files.
+    // .info files override module definitions.
     foreach (libraries_scan_info_files() as $name => $file) {
       $properties = drupal_parse_info_file($file->uri);
       $properties['info file'] = $file->uri;
@@ -199,10 +200,11 @@ function libraries_info($library = NULL) {
     // Provide defaults.
     foreach ($libraries as $name => &$properties) {
       $properties += array(
-        'title' => $name,
+        'name' => $name,
         'vendor url' => '',
         'download url' => '',
         'path' => '',
+        'library path' => NULL,
         'version callback' => 'libraries_get_version',
         'version arguments' => array(),
         'files' => array(),
@@ -265,7 +267,7 @@ function libraries_detect_library(&$library) {
   }
   if (!file_exists($library['library path'])) {
     $library['error'] = 'not found';
-    $library['error message'] = t('%library could not be found.', array('%library' => $library['title']));
+    $library['error message'] = t('%library could not be found.', array('%library' => $library['name']));
     return;
   }
 
@@ -282,7 +284,7 @@ function libraries_detect_library(&$library) {
     }
     if (empty($library['version'])) {
       $library['error'] = 'not detected';
-      $library['error message'] = t('The version of %library could not be detected.', array('%library' => $library['title']));
+      $library['error message'] = t('The version of %library could not be detected.', array('%library' => $library['name']));
       return;
     }
   }
@@ -300,7 +302,7 @@ function libraries_detect_library(&$library) {
       $library['error'] = 'not supported';
       $library['error message'] = t('The installed version %version of %library is not supported.', array(
         '%version' => $library['version'],
-        '%library' => $library['title'],
+        '%library' => $library['name'],
       ));
       return;
     }
@@ -315,8 +317,10 @@ function libraries_detect_library(&$library) {
     foreach ($library['variants'] as $name => &$variant) {
       // If no variant callback has been set, assume the variant to be
       // installed.
-      $variant['installed'] = TRUE;
-      if (!empty($variant['variant callback'])) {
+      if (!isset($variant['variant callback'])) {
+        $variant['installed'] = TRUE;
+      }
+      else {
         // We support both a single parameter, which is an associative array,
         // and an indexed array of multiple parameters.
         if (isset($variant['variant arguments'][0])) {
@@ -326,11 +330,11 @@ function libraries_detect_library(&$library) {
         else {
           $variant['installed'] = $variant['variant callback']($library, $name, $variant['variant arguments']);
         }
-        if (empty($variant['installed'])) {
+        if (!$variant['installed']) {
           $variant['error'] = 'not found';
           $variant['error message'] = t('The %variant variant of %library could not be found.', array(
             '%variant' => $name,
-            '%library' => $library['title'],
+            '%library' => $library['name'],
           ));
         }
       }
@@ -344,49 +348,61 @@ function libraries_detect_library(&$library) {
 /**
  * Loads a library.
  *
- * @param $library
+ * @param $name
  *   The name of the library to load.
  * @param $variant
  *   The name of the variant to load.
  */
-function libraries_load($library, $variant = NULL) {
-  $library = libraries_info($library);
+function libraries_load($name, $variant = NULL) {
+  $library = libraries_info($name);
   libraries_detect_library($library);
-  if ($library['installed']) {
-    libraries_load_files($library, $variant);
-    return TRUE;
+
+  // If the library itself is not installed, do nothing;
+  if (!$library['installed']) {
+    return FALSE;
+  }
+
+  // If a variant was specified, override the top-level properties with the
+  // variant properties.
+  if (!empty($variant) && !empty($library['variants'][$variant])) {
+    // If the variant is not installed, do nothing.
+    if (!$library['variants'][$variant]['installed']) {
+      return FALSE;
+    }
+    $library = array_merge($library, $library['variants'][$variant]);
   }
-  return FALSE;
+
+  return libraries_load_files($library, $variant);
 }
 
 /**
  * Loads a library's files.
  *
  * @param $library
- *   The name of the library to load.
- * @param $variant
- *   The name of the variant to load.
+ *   An array of library information as returned by libraries_info().
+ *
+ * @return
+ *   The number of loaded files.
  */
-function libraries_load_files($library, $variant = NULL) {
-  // Construct the full path to the library for later use.
-  $path = (!empty($library['path']) ? $library['library path'] . '/' . $library['path'] : $library['library path']);
-
-  // If a variant was specified, override the top-level properties with the
-  // variant properties.
-  if (!empty($variant) && !empty($library['variants'][$variant]['installed'])) {
-    $library = array_merge($library, $library['variants'][$variant]);
-  }
-
+function libraries_load_files($library) {
   // Load integration files.
   if (!empty($library['integration files'])) {
     foreach ($library['integration files'] as $module => $files) {
       libraries_load_files(array(
         'files' => $files,
+        'path' => '',
         'library path' => drupal_get_path('module', $module),
       ));
     }
   }
 
+  // Construct the full path to the library for later use.
+  $path = $library['library path'];
+  $path = ($library['path'] !== '' ? $path . '/' . $library['path'] : $path);
+
+  // Count the number of loaded files for the return value.
+  $count = 0;
+
   // Load both the JavaScript and the CSS files.
   // The parameters for drupal_add_js() and drupal_add_css() require special
   // handling.
@@ -413,6 +429,7 @@ function libraries_load_files($library, $variant = NULL) {
           $options['weight'] = ($type == 'js') ? JS_DEFAULT : CSS_DEFAULT;
         }
         call_user_func('drupal_add_' . $type, $data, $options);
+        $count++;
       }
     }
   }
@@ -423,9 +440,12 @@ function libraries_load_files($library, $variant = NULL) {
       $file_path = DRUPAL_ROOT . '/' . $path . '/' . $file;
       if (file_exists($file_path)) {
         require_once $file_path;
+        $count++;
       }
     }
   }
+
+  return $count;
 }
 
 /**

tests/example/example_1.css

@@ -4,10 +4,9 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Color the 'libraries-test' div red. See example_installed.txt for more
- * information.
+ * Color the 'libraries-test-css' div red. See README.txt for more information.
  */
 
-div#libraries-test {
+.libraries-test-css {
   color: red;
 }

tests/example/example_1.js

@@ -4,15 +4,15 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Insert a 'libraries-test' div and some text below the page title. See
- * example_installed.txt for more information.
+ * Replace the text in the 'libraries-test-javascript' div. See README.txt for
+ * more information.
  */
 
 (function ($) {
 
 Drupal.behaviors.librariesTest = {
   attach: function(context, settings) {
-    $('h1#page-title').after('<div id="libraries-test">If this text shows up, the JavaScript file was loaded successfully. If this text is red, the CSS file was loaded successfully.</div>')
+    $('.libraries-test-javascript').text('If this text shows up, example_1.js was loaded successfully')
   }
 };
 

tests/example/example_2.css

@@ -4,10 +4,9 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Color the 'libraries-test' div green. See example_installed.txt for more
- * information.
+ * Color the 'libraries-test-css' div green. See README.txt for more information.
  */
 
-div#libraries-test {
+.libraries-test-css {
   color: green;
 }

tests/example/example_2.js

@@ -4,15 +4,15 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Insert a 'libraries-test' div and some text below the page title. See
- * example_installed.txt for more information.
+ * Replace the text in the 'libraries-test-javascript' div. See README.txt for
+ * more information.
  */
 
 (function ($) {
 
 Drupal.behaviors.librariesTest = {
   attach: function(context, settings) {
-    $('h1#page-title').after('<div id="libraries-test">If this text shows up, the JavaScript file was loaded successfully. If this text is green, the CSS file was loaded successfully.</div>')
+    $('.libraries-test-javascript').text('If this text shows up, example_2.js was loaded successfully')
   }
 };
 

tests/example/example_3.css

@@ -4,10 +4,9 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Color the 'libraries-test' div orange. See example_installed.txt for more
- * information.
+ * Color the 'libraries-test-css' div orange. See README.txt for more information.
  */
 
-div#libraries-test {
+.libraries-test-css {
   color: orange;
 }

tests/example/example_3.js

@@ -4,15 +4,15 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Insert a 'libraries-test' div and some text below the page title. See
- * example_installed.txt for more information.
+ * Replace the text in the 'libraries-test-javascript' div. See README.txt for
+ * more information.
  */
 
 (function ($) {
 
 Drupal.behaviors.librariesTest = {
   attach: function(context, settings) {
-    $('h1#page-title').after('<div id="libraries-test">If this text shows up, the JavaScript file was loaded successfully. If this text is orange, the CSS file was loaded successfully.</div>')
+    $('.libraries-test-javascript').text('If this text shows up, example_3.js was loaded successfully')
   }
 };
 

tests/example/example_4.css

@@ -4,10 +4,9 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Color the 'libraries-test' div blue. See example_installed.txt for more
- * information.
+ * Color the 'libraries-test-css' div blue. See README.txt for more information.
  */
 
-div#libraries-test {
+.libraries-test-css {
   color: blue;
 }

tests/example/example_4.js

@@ -4,15 +4,15 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Insert a 'libraries-test' div and some text below the page title. See
- * example_installed.txt for more information.
+ * Replace the text in the 'libraries-test-javascript' div. See README.txt for
+ * more information.
  */
 
 (function ($) {
 
 Drupal.behaviors.librariesTest = {
   attach: function(context, settings) {
-    $('h1#page-title').after('<div id="libraries-test">If this text shows up, the JavaScript file was loaded successfully. If this text is blue, the CSS file was loaded successfully.</div>')
+    $('.libraries-test-javascript').text('If this text shows up, example_4.js was loaded successfully')
   }
 };
 

tests/libraries.test

@@ -30,65 +30,83 @@ class LibrariesTestCase extends DrupalWebTestCase {
    * @todo Better method name(s); split into detection/loading/overloading/etc.
    */
   function testLibraries() {
+    // Test that library information is found correctly.
+    $library = libraries_info('example_simple');
+    $expected = array_merge(libraries_info('example_empty'), array(
+      'name' => 'Example simple',
+      'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
+      'version callback' => '_libraries_test_return_version',
+      'version arguments' => array('1'),
+      'files' => array(
+        'js' => array('example_1.js'),
+        'css' => array('example_1.css'),
+        'php' => array('example_1.php'),
+      ),
+    ));
+    $this->verbose(var_export($expected, TRUE));
+    $this->verbose(var_export($library, TRUE));
+    $this->assertEqual($library, $expected, 'Library information is correctly gathered.');
+
     // Test a library specified with an .info file gets detected.
-    $library = libraries_info('example');
-    $expected = array(
-      'title' => 'example',
-      'vendor url' => '',
-      'download url' => '',
-      'path' => '',
-      'version callback' => 'libraries_get_version',
-      'version arguments' => array(),
-      'files' => array(),
-      'variants' => array(),
-      'versions' => array(),
-      'integration files' => array(),
-    );
+    $library = libraries_info('example_info_file');
+    $expected = array_merge(libraries_info('example_empty'), array(
+      'name' => 'Example info file',
+      'info file' => drupal_get_path('module', 'libraries_test') . '/example/example_info_file.libraries.info',
+    ));
+    unset($expected['module']);
+    $this->verbose(var_export($expected, TRUE));
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library, $expected, 'Library specified with an .info file found');
 
     // Test missing library.
     $library = libraries_info('example_missing');
     libraries_detect_library($library);
-    $this->assertEqual($library['error'], 'not found', 'Non-existing library not found.');
+    $this->verbose(var_export($library, TRUE));
+    $this->assertEqual($library['error'], 'not found', 'Missing library not found.');
     $error_message = t('%library could not be found.', array(
-      '%library' => $library['title'],
+      '%library' => $library['name'],
     ));
     $this->assertEqual($library['error message'], $error_message, 'Correct error message for a missing library.');
 
     // Test unknown library version.
     $library = libraries_info('example_undetected_version');
     libraries_detect_library($library);
-    $this->assertEqual($library['error'], 'not detected', 'Library version not found.');
+    $this->verbose(var_export($library, TRUE));
+    $this->assertEqual($library['error'], 'not detected', 'Undetected version detected as such.');
     $error_message = t('The version of %library could not be detected.', array(
-      '%library' => $library['title'],
+      '%library' => $library['name'],
     ));
     $this->assertEqual($library['error message'], $error_message, 'Correct error message for a library with an undetected version.');
 
     // Test unsupported library version.
     $library = libraries_info('example_unsupported_version');
     libraries_detect_library($library);
-    $this->assertEqual($library['error'], 'not supported', 'Library version not supported.');
+    $this->verbose(var_export($library, TRUE));
+    $this->assertEqual($library['error'], 'not supported', 'Unsupported version detected as such.');
     $error_message = t('The installed version %version of %library is not supported.', array(
       '%version' => $library['version'],
-      '%library' => $library['title'],
+      '%library' => $library['name'],
     ));
     $this->assertEqual($library['error message'], $error_message, 'Correct error message for a library with an unsupported version.');
 
     // Test supported library version.
     $library = libraries_info('example_supported_version');
     libraries_detect_library($library);
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library['installed'], TRUE, 'Supported library version found.');
 
     // Test libraries_get_version().
     $library = libraries_info('example_default_version_callback');
     libraries_detect_library($library);
     $version = '2';
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library['version'], $version, 'Expected version returned by default version callback.');
 
     // Test a multiple-parameter version callback.
     $library = libraries_info('example_multiple_parameter_version_callback');
     libraries_detect_library($library);
     $version = '2';
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library['version'], $version, 'Expected version returned by multiple parameter version callback.');
 
     // Test a top-level files property.
@@ -99,6 +117,7 @@ class LibrariesTestCase extends DrupalWebTestCase {
       'css' => array('example_1.css'),
       'php' => array('example_1.php'),
     );
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library['files'], $files, 'Top-level files property works.');
 
     // Test version-specific library files.
@@ -109,45 +128,48 @@ class LibrariesTestCase extends DrupalWebTestCase {
       'css' => array('example_2.css'),
       'php' => array('example_2.php'),
     );
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library['files'], $files, 'Version-specific library files found.');
 
     // Test missing variant.
     $library = libraries_info('example_variant_missing');
     libraries_detect_library($library);
     $variants = array_keys($library['variants']);
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library['variants']['example_variant']['error'], 'not found', 'Missing variant not found');
     $error_message = t('The %variant variant of %library could not be found.', array(
       '%variant' => $variants[0],
-      '%library' => $library['title'],
+      '%library' => $library['name'],
     ));
     $this->assertEqual($library['variants']['example_variant']['error message'], $error_message, 'Correct error message for a missing variant.');
 
     // Test existing variant.
     $library = libraries_info('example_variant');
     libraries_detect_library($library);
+    $this->verbose(var_export($library, TRUE));
     $this->assertEqual($library['variants']['example_variant']['installed'], TRUE, 'Existing variant found.');
 
     // Test loading of a simple library with a top-level files property.
     $this->drupalGet('libraries_test/simple');
-    $this->assertLibraryFiles('example_1');
+    $this->assertLibraryFiles('example_1', 'Simple library loading');
 
     // Test loading of integration files.
     $this->drupalGet('libraries_test/integration_files');
-    $this->assertRaw('libraries_test.js', 'The JavaScript integration file is loaded.');
-    $this->assertRaw('libraries_test.css', 'The CSS integration file is loaded.');
-    $this->assertText('libraries_test.inc', 'The PHP integration file is loaded.');
+    $this->assertRaw('libraries_test.js', 'Integration file loading: libraries_test.js found');
+    $this->assertRaw('libraries_test.css', 'Integration file loading: libraries_test.css found');
+    $this->assertRaw('libraries_test.inc', 'Integration file loading: libraries_test.inc found');
 
     // Test version overloading.
     $this->drupalGet('libraries_test/versions');
-    $this->assertLibraryFiles('example_2');
+    $this->assertLibraryFiles('example_2', 'Version overloading');
 
     // Test variant loading.
     $this->drupalGet('libraries_test/variant');
-    $this->assertLibraryFiles('example_3');
+    $this->assertLibraryFiles('example_3', 'Variant loading');
 
     // Test version overloading and variant loading.
     $this->drupalGet('libraries_test/versions_and_variants');
-    $this->assertLibraryFiles('example_4');
+    $this->assertLibraryFiles('example_4', 'Concurrent version and variant overloading');
   }
 
   /**
@@ -163,22 +185,32 @@ class LibrariesTestCase extends DrupalWebTestCase {
    *   other files will be asserted to not be loaded. See
    *   tests/example/README.txt for more information on how the loading of the
    *   files is tested.
+   * @param $label
+   *   (optional) A label to prepend to the assertion messages, to make them
+   *   less ambiguous.
+   * @param $extensions
+   *   (optional) The expected file extensions of $name. Defaults to
+   *   array('js', 'css', 'php').
    */
-  function assertLibraryFiles($name) {
+  function assertLibraryFiles($name, $label = '', $extensions = array('js', 'css', 'php')) {
     $names = drupal_map_assoc(array('example_1', 'example_2', 'example_3', 'example_4'));
     unset($names[$name]);
 
     // Test that the wrong files are not loaded.
     foreach ($names as $filename) {
-      $this->assertNoRaw("$filename.js", 'A wrong JavaScript file is not loaded.');
-      $this->assertNoRaw("$filename.css", 'A wrong CSS file is not loaded.');
-      $this->assertNoText("$filename.php", 'A wrong PHP file is not loaded.');
+      foreach ($extensions as $extension) {
+        $message = "$filename.$extension not found";
+        $message = ($label !== '' ? "$label: $message" : $message);
+        $this->assertNoRaw("$filename.$extension", $message);
+      }
     }
 
     // Test that the correct files are loaded.
-    $this->assertRaw("$name.js", 'The correct JavaScript file is loaded.');
-    $this->assertRaw("$name.css", 'The correct CSS file is loaded.');
-    $this->assertText("$name.php", 'The correct PHP file is loaded.');
+    foreach ($extensions as $extension) {
+      $message = "$filename.$extension found";
+      $message = ($label !== '' ? "$label: $message" : $message);
+      $this->assertRaw("$name.$extension", $message);
+    }
   }
 
 }

tests/libraries_test.css

@@ -4,12 +4,9 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Because we cannot test CSS programatically with SimpleTest, the CSS below can
- * be useful for debugging with SimpleTest's verbose mode. Note that since the
- * DOM cannot be manipulated via CSS, JavaScript loading needs to be functional
- * for this to have any visible effect.
+ * Color the 'libraries-test-css' div blue. See README.txt for more information.
  */
 
-div#libraries-test {
+.libraries-test-css {
   color: purple;
 }

tests/libraries_test.js

@@ -4,15 +4,15 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Because we cannot test JavaScript programatically with SimpleTest, the
- * JavaScript below can be useful for debugging with SimpleTest's verbose mode.
+ * Replace the text in the 'libraries-test-javascript' div. See README.txt for
+ * more information.
  */
 
 (function ($) {
 
 Drupal.behaviors.librariesTest = {
   attach: function(context, settings) {
-    $('h1#page-title').after('<div id="libraries-test">If this text shows up, the JavaScript file was loaded successfully. If this text is purple, the CSS file was loaded successfully.</div>')
+    $('.libraries-test-javascript').text('If this text shows up, libraries_test.js was loaded successfully')
   }
 };
 

tests/libraries_test.module

@@ -12,22 +12,19 @@
 function libraries_test_libraries_info() {
   // Test library detection.
   $libraries['example_missing'] = array(
-    'title' => 'Example missing',
-    // Never declare library path manually. It is detected automatically.
+    'name' => 'Example missing',
     'library path' => drupal_get_path('module', 'libraries') . '/tests/missing',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('1'),
   );
   $libraries['example_undetected_version'] = array(
-    'title' => 'Example undetected version',
-    // Never declare library path manually. It is detected automatically.
+    'name' => 'Example undetected version',
     'library path' => drupal_get_path('module', 'libraries') . '/tests',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array(FALSE),
   );
   $libraries['example_unsupported_version'] = array(
-    'title' => 'Example unsupported version',