Commit d033c260 authored by Tobias Stoeckler's avatar Tobias Stoeckler

#719896: followup by tstoeckler, sun: Improve documentation for...

#719896: followup by tstoeckler, sun: Improve documentation for hook_libraries_info and restructure tests
parent 3c1653be
......@@ -21,17 +21,21 @@
* actual library. Only required if the extracted download package contains
* the actual library files in a sub-directory.
* - version callback: (optional) The name of a function that detects and
* returns the full version string of the library. Defaults to
* libraries_get_version(). The first argument is always $library, an array
* containing all library information as described here. The following
* argument(s) can either be:
* - options: An associative array of additional information to pass to the
* version callback. In this case the version arguments (see below) must
* be declared as an associative array.
* - or any number of independent arguments. In this case the version
* arguments (see below) must be declared as an indexed array.
* 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().
* - version arguments: A list of arguments to pass to the version callback.
* The default version callback libraries_get_version() expects a single,
* 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 seperate 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 library
* path. For example: 'docs/changelog.txt'.
......@@ -59,17 +63,21 @@
* - variant callback: (optional) The name of a function that detects
* 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 seconds argument is always
* $name, a string containing the name of the variant. The following
* argument(s) can either be:
* - options: An associative array of additional information to pass to
* the version callback. In this case the version arguments (see below)
* must be declared as an associative array.
* - or any number of independent arguments. In this case the version
* arguments (see below) must be declared as an indexed array.
* If ommitted, the variant is expected to always be available. Variants
* can be version specific.
* library information as described here. The second is always a string
* containing the variant name. There are two ways to declare the variant
* callback's additinal 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 ommitted, 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 seperate arguments in the order they were declared.
* Variants can be version specific.
* - versions: (optional) An associative array of supported library versions.
* Naturally, external libraries evolve over time and so do their APIs. In
* case a library changes between versions, different 'files' may need to be
......
; $Id$
Example library
Version 2
This file is an example file to test version detection.
/* $Id$ */
/**
* @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.
*/
div#libraries-test {
color: red;
}
// $Id$
/**
* @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.
*/
(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>')
}
};
})(jQuery);
<?php
// $Id$
/**
* @file
* Test PHP file for Libraries loading.
*/
/**
* Dummy function to see if this file was loaded.
*/
function _libraries_example_installed_1() {
}
/* $Id$ */
/**
* @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.
*/
div#libraries-test {
color: green;
}
// $Id$
/**
* @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.
*/
(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>')
}
};
})(jQuery);
<?php
// $Id$
/**
* @file
* Test PHP file for Libraries loading.
*/
/**
* Dummy function to see if this file was loaded.
*/
function _libraries_example_installed_2() {
}
/* $Id$ */
/**
* @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.
*/
div#libraries-test {
color: orange;
}
// $Id$
/**
* @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.
*/
(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>')
}
};
})(jQuery);
<?php
// $Id$
/**
* @file
* Test PHP file for Libraries loading.
*/
/**
* Dummy function to see if this file was loaded.
*/
function _libraries_example_installed_variant_1() {
}
/* $Id$ */
/**
* @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.
*/
div#libraries-test {
color: blue;
}
// $Id$
/**
* @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.
*/
(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>')
}
};
})(jQuery);
<?php
// $Id$
/**
* @file
* Test PHP file for Libraries loading.
*/
/**
* Dummy function to see if this file was loaded.
*/
function _libraries_example_installed_variant_2() {
}
......@@ -72,9 +72,9 @@ class LibrariesTestCase extends DrupalWebTestCase {
$library = libraries_info('example_simple');
libraries_detect_library($library);
$files = array(
'js' => array('example_installed_1.js'),
'css' => array('example_installed_1.css'),
'php' => array('example_installed_1.php'),
'js' => array('example_1.js'),
'css' => array('example_1.css'),
'php' => array('example_1.php'),
);
$this->assertEqual($library['files'], $files, 'Top-level files property works.');
......@@ -82,9 +82,9 @@ class LibrariesTestCase extends DrupalWebTestCase {
$library = libraries_info('example_versions');
libraries_detect_library($library);
$files = array(
'js' => array('example_installed_2.js'),
'css' => array('example_installed_2.css'),
'php' => array('example_installed_2.php'),
'js' => array('example_2.js'),
'css' => array('example_2.css'),
'php' => array('example_2.php'),
);
$this->assertEqual($library['files'], $files, 'Version-specific library files found.');
......@@ -96,18 +96,16 @@ class LibrariesTestCase extends DrupalWebTestCase {
'%variant' => $variants[0],
'%library' => $library['title'],
));
$this->assertEqual($library['variants']['example_variant_1']['error'], $error, 'Missing variant not found.');
$this->assertEqual($library['variants']['example_variant']['error'], $error, 'Missing variant not found.');
// Test existing variant.
$library = libraries_info('example_variant');
libraries_detect_library($library);
$this->assertEqual($library['variants']['example_variant_1']['installed'], TRUE, 'Existing variant found.');
$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->assertRaw('example_installed_1.js', 'A JavaScript file is loaded correctly.');
$this->assertRaw('example_installed_1.css', 'A CSS file is loaded correctly.');
$this->assertText('example_installed_1.php', 'A PHP file is loaded correctly.');
$this->assertLibraryFiles('example_1');
// Test loading of integration files.
$this->drupalGet('libraries_test/integration_files');
......@@ -117,37 +115,47 @@ class LibrariesTestCase extends DrupalWebTestCase {
// Test version overloading.
$this->drupalGet('libraries_test/versions');
$this->assertNoRaw('example_installed_1.js', 'The JavaScript file of the wrong library version is not loaded.');
$this->assertNoRaw('example_installed_1.css', 'The CSS file of the wrong library version is not loaded.');
$this->assertNoText('example_installed_1.php', 'The PHP file of the wrong library version is not loaded.');
$this->assertRaw('example_installed_2.js', 'The JavaScript file of the correct library version is loaded.');
$this->assertRaw('example_installed_2.css', 'The CSS file of the correct library version is loaded.');
$this->assertText('example_installed_2.php', 'The PHP file of the correct library version is loaded.');
$this->assertLibraryFiles('example_2');
// Test variant loading.
$this->drupalGet('libraries_test/variant');
$this->assertNoRaw('example_installed_variant_2.js', 'The JavaScript file of the wrong library variant is not loaded.');
$this->assertNoRaw('example_installed_variant_2.css', 'The CSS file of the wrong library variant is not loaded.');
$this->assertNoText('example_installed_variant_2.php', 'The PHP file of the wrong library variant is not loaded.');
$this->assertRaw('example_installed_variant_1.js', 'The JavaScript file of the correct library variant is loaded.');
$this->assertRaw('example_installed_variant_1.css', 'The CSS file of the correct library variant is loaded.');
$this->assertText('example_installed_variant_1.php', 'The PHP file of the correct library variant is loaded.');
$this->assertLibraryFiles('example_3');
// Test version overloading and variant loading.
$this->drupalGet('libraries_test/versions_and_variants');
$this->assertNoRaw('example_installed_1.js', 'The JavaScript file of the wrong library version and variant is not loaded.');
$this->assertNoRaw('example_installed_1.css', 'The CSS file of the wrong library version and variant is not loaded.');
$this->assertNoText('example_installed_1.php', 'The PHP file of the wrong library version and variant is not loaded.');
$this->assertNoRaw('example_installed_2.js', 'The JavaScript file of the wrong library version and variant is not loaded.');
$this->assertNoRaw('example_installed_2.css', 'The CSS file of the wrong library version and variant is not loaded.');
$this->assertNoText('example_installed_2.php', 'The PHP file of the wrong library version and variant is not loaded.');
$this->assertNoRaw('example_installed_variant_1.js', 'The JavaScript file of the wrong library version and variant is not loaded.');
$this->assertNoRaw('example_installed_variant_1.css', 'The CSS file of the wrong library version and variant is not loaded.');
$this->assertNoText('example_installed_variant_1.php', 'The PHP file of the wrong library version and variant is not loaded.');
$this->assertRaw('example_installed_variant_2.js', 'The JavaScript file of the correct library version and variant is loaded.');
$this->assertRaw('example_installed_variant_2.css', 'The CSS file of the correct library version and variant is loaded.');
$this->assertText('example_installed_variant_2.php', 'The PHP file of the correct library version and variant is loaded.');
$this->assertLibraryFiles('example_4');
}
/**
* Helper function to assert that a library was correctly loaded.
*
* Asserts that all the correct files were loaded and all the incorrect ones
* were not.
*
* @param $name
* The name of the files that should be loaded. The current testing system
* knows of 'example_1', 'example_2', 'example_3' and 'example_4'. Each name
* has an associated JavaScript, CSS and PHP file that will be asserted. All
* 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.
*/
private function assertLibraryFiles($name) {
$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.');
}
// 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.');
}
}
......@@ -8,5 +8,5 @@
/**
* Dummy function to see if this file was loaded.
*/
function libraries_test_1() {
function _libraries_test_integration_file() {
}
......@@ -16,4 +16,4 @@ Drupal.behaviors.librariesTest = {
}
};
})(jQuery);
})(jQuery);
......@@ -8,24 +8,23 @@
/**
* Implements hook_libraries_info().
*
* Note: DO NOT use drupal_get_path() in your implementations! Used for testing
* purposes only. It is strongly discouraged to declare the 'library path'
* property as that will be detected by Libraries API automatically.
*/
function libraries_test_libraries_info() {
// Test library detection.
$libraries['example_missing'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/missing',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('1'),
);
$libraries['example_undetected_version'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests',
'version callback' => '_libraries_test_return_version',
'version arguments' => array(FALSE),
);
$libraries['example_unsupported_version'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('1'),
......@@ -35,6 +34,7 @@ function libraries_test_libraries_info() {
);
$libraries['example_supported_version'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('2'),
......@@ -45,9 +45,10 @@ function libraries_test_libraries_info() {
// Test the default version callback.
$libraries['example_default_version_callback'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
'version arguments' => array(
'file' => 'example_installed.txt',
'file' => 'README.txt',
// Version 2
'pattern' => '/Version (\d+)/',
'lines' => 5,
......@@ -56,26 +57,28 @@ function libraries_test_libraries_info() {
// Test a multiple-parameter version callback.
$libraries['example_multiple_parameter_version_callback'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
// Version 2
'version callback' => '_libraries_get_version',
'version arguments' => array('example_installed.txt', '/Version (\d+)/', 5),
'version callback' => '_libraries_test_get_version',
'version arguments' => array('README.txt', '/Version (\d+)/', 5),
);
// Test a top-level files property.
$libraries['example_simple'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('1'),
'files' => array(
'js' => array(
'example_installed_1.js',
'example_1.js',
),
'css' => array(
'example_installed_1.css',
'example_1.css',
),
'php' => array(
'example_installed_1.php'
'example_1.php'
),
),
);
......@@ -84,6 +87,7 @@ function libraries_test_libraries_info() {
// Normally added by the corresponding module via hook_libraries_info_alter(),
// these files should be automatically loaded when the library is loaded.
$libraries['example_integration_files'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('2'),
......@@ -104,6 +108,7 @@ function libraries_test_libraries_info() {
// Test version overloading.
$libraries['example_versions'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('2'),
......@@ -111,26 +116,26 @@ function libraries_test_libraries_info() {
'1' => array(
'files' => array(
'js' => array(
'example_installed_1.js',
'example_1.js',
),
'css' => array(
'example_installed_1.css',
'example_1.css',
),
'php' => array(
'example_installed_1.php',
'example_1.php',
),
),
),
'2' => array(
'files' => array(
'js' => array(
'example_installed_2.js',
'example_2.js',
),
'css' => array(
'example_installed_2.css',
'example_2.css',
),
'php' => array(
'example_installed_2.php',
'example_2.php',
),
),
),
......@@ -139,61 +144,63 @@ function libraries_test_libraries_info() {
// Test variant detection.
$libraries['example_variant_missing'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('2'),
'variants' => array(
'example_variant_1' => array(
'example_variant' => array(
'files' => array(
'js' => array(
'example_installed_variant_1.js',
'example_3.js',
),
'css' => array(
'example_installed_variant_1.css',
'example_3.css',
),
'php' => array(
'example_installed_variant_1.php',
'example_3.php',
),
),
'variant callback' => '_libraries_test_detect_variant',
'variant callback' => '_libraries_test_return_installed',
'variant arguments' => array(FALSE),
),
),
);
$libraries['example_variant'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
'version callback' => '_libraries_test_return_version',
'version arguments' => array('2'),
'variants' => array(
'example_variant_1' => array(
'example_variant' => array(
'files' => array(
'js' => array(
'example_installed_variant_1.js',
'example_3.js',
),
'css' => array(
'example_installed_variant_1.css',
'example_3.css',
),
'php' => array(
'example_installed_variant_1.php',
'example_3.php',
),
),
'variant callback' => '_libraries_test_detect_variant',
'variant callback' => '_libraries_test_return_installed',
'variant arguments' => array(TRUE),
),
'example_variant_2' => array(
'files' => array(
'js' => array(
'example_installed_variant_2.js',
'example_4.js',
),
'css' => array(
'example_installed_variant_2.css',
'example_4.css',
),
'php' => array(
'example_installed_variant_2.php',
'example_4.php',
),
),
'variant callback' => '_libraries_test_detect_variant',
'variant callback' => '_libraries_test_return_installed',
'variant arguments' => array(TRUE),
),
),
......@@ -201,6 +208,7 @@ function libraries_test_libraries_info() {
// Test correct behaviour with multiple versions and multiple variants.
$libraries['example_versions_and_variants'] = array(
// Never declare library path manually. It is detected automatically.
'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
'version callback' => '_libraries_test_return_version',