crm.fsf.org/20131203/files/sites/all/modules-old/libraries/libraries.admin.inc

   1 <?php
   2
   3 /**
   4  * @file
   5  * Provides administrative page and form callbacks for Libraries module.
   6  */
   7
   8 /**
   9  * Form generation callback for the libraries overview table.
  10  *
  11  * This is a form instead of a page to allow easier extending in contributed
  12  * modules.
  13  *
  14  * @param array $form
  15  *   An associative array containing the structure of the form.
  16  * @param array $form_state
  17  *   A keyed array containing the current state of the form.
  18  *
  19  * @return array
  20  *   The form array for the overview form.
  21  */
  22 function libraries_admin_overview(array $form, array &$form_state) {
  23   $header = array(t('Name'), t('Status'), t('Installed version'), t('Provider'), t('Links'));
  24   $rows = array();
  25
  26   $libraries = libraries_detect();
  27   uasort($libraries, 'libraries_admin_sort_title');
  28
  29   foreach ($libraries as $machine_name => $library) {
  30     $actions = array();
  31
  32     if ($library['vendor url']) {
  33       $actions[] = l('Homepage', $library['vendor url']);
  34     }
  35     if ($library['download url']) {
  36       $actions[] = l('Download', $library['download url']);
  37     }
  38
  39     $rows[] = array(
  40       'data' => array(
  41         l($library['name'], 'admin/reports/libraries/' . $machine_name),
  42         ($library['installed'] ? t('OK') : drupal_ucfirst($library['error'])),
  43         (isset($library['version']) ? $library['version'] : ''),
  44         libraries_admin_get_provider_with_type($library),
  45         implode(' | ', $actions),
  46       ),
  47       'class' => ($library['installed'] ? array('ok') : array('error')),
  48     );
  49   }
  50
  51   $form['libraries']['list'] = array(
  52     '#theme' => 'table',
  53     '#header' => $header,
  54     '#rows' => $rows,
  55     '#empty' => t('There are currently no libraries installed'),
  56   );
  57
  58   return $form;
  59 }
  60
  61 /**
  62  * Form generation callback for the status overview for a single library.
  63  *
  64  * This is a form instead of a page to allow easier extending in contributed
  65  * modules.
  66  *
  67  * @param array $form
  68  *   An associative array containing the structure of the form.
  69  * @param array $form_state
  70  *   A keyed array containing the current state of the form.
  71  * @param array $library
  72  *   A library information array.
  73  *
  74  * @return array|null
  75  *   The form array for the status form or NULL if the library was not found.
  76  *
  77  * @todo Add some var_export($library)-style output
  78  */
  79 function libraries_admin_library_status_form(array $form, array &$form_state, $library) {
  80   drupal_set_title(t('Status report for library %library', array('%library' => $library['name'])), PASS_THROUGH);
  81
  82   if ($library['installed']) {
  83     drupal_set_message(t('The %name library is installed correctly.', array('%name' => $library['name'])));
  84     $form['status'] = libraries_admin_status_table($library);
  85   }
  86   else {
  87     drupal_set_message($library['error message'], 'error');
  88     switch ($library['error']) {
  89       case 'not found':
  90         $form['instructions'] = libraries_admin_instructions_missing($library);
  91         break;
  92
  93       case 'not detected':
  94         $form['instructions'] = libraries_admin_instructions_undetected($library);;
  95         break;
  96
  97       case 'not supported':
  98         $form['instructions'] = libraries_admin_instructions_unsupported($library);
  99         break;
 100
 101       case 'missing dependency':
 102         $form['instructions']['instruction']['#markup'] = t('There a missing dependency in your configuration that prevent this library to work properly.') . '<br>';
 103         break;
 104
 105       case 'incompatible dependency':
 106         $form['instructions']['instruction']['#markup'] = t('There an incompatible dependency in your configuration that prevent this library to work properly.') . '<br>';
 107         break;
 108     }
 109   }
 110
 111   return $form;
 112 }
 113
 114
 115 /**
 116  * Displays a table of status information about a library.
 117  *
 118  * @param array $library
 119  *   A library information array.
 120  *
 121  * @return array
 122  *   A renderable array containing a table with status information.
 123  */
 124 function libraries_admin_status_table(array $library) {
 125   $header = array(array(
 126     // @todo The title implies that other type of information is displayed, as
 127     //   well, but this is currently not the case.
 128     // @todo Use CSS instead of a <strong> element.
 129     'data' => '<strong>' . t('General information') . '</strong>',
 130     'colspan' => 2,
 131     'class' => 'table-heading',
 132     'no_striping' => TRUE,
 133   ));
 134
 135   $rows = array();
 136   // @todo Use CSS instead of <strong> elements.
 137   $rows['name'] = array('<strong>' . t('Name') . '</strong>', check_plain($library['name']));
 138   $rows['machine_name'] = array('<strong>' . t('Machine name') . '</strong>', check_plain($library['machine name']));
 139   if ($library['vendor url']) {
 140     $rows['vendor_url'] = array('<strong>' . t('Vendor URL') . '</strong>', l($library['vendor url'], $library['vendor url']));
 141   }
 142   if ($library['download url']) {
 143     $rows['download_url'] = array('<strong>' . t('Download URL') . '</strong>', l($library['download url'], $library['download url']));
 144   }
 145   $rows['provider'] = array('<strong>' . t('Provider') . '</strong>', libraries_admin_get_provider_with_type($library));
 146   $rows['library_path'] = array('<strong>' . t('Library path') . '</strong>', $library['library path']);
 147   $rows['version'] = array('<strong>' . t('Version') . '</strong>', $library['version']);
 148   if (!empty($library['variants'])) {
 149     $rows['variants'] = array('<strong>' . t('Variants') . '</strong>', implode(', ', array_keys($library['variants'])));
 150   }
 151
 152   return array(
 153     '#theme' => 'table',
 154     '#header' => $header,
 155     '#rows' => $rows,
 156   );
 157 }
 158
 159 /**
 160  * Returns instructions for dealing with a missing library.
 161  *
 162  * @param array $library
 163  *   A library information array.
 164  *
 165  * @return array
 166  *   A renderable array containing the instructions.
 167  */
 168 function libraries_admin_instructions_missing(array $library) {
 169   $build = array();
 170
 171   $build['instruction']['#markup'] = t('Follow these steps to install the library:');
 172
 173   $items = array();
 174   // 1. Download the library.
 175   // If no supported versions are specified, the latest version is
 176   // recommended.
 177   if (empty($library['versions'])) {
 178     $items[] = t('Download the latest version of the library <a href="@download-url">here</a>.', array(
 179       '@download-url' => $library['download url'],
 180     ));
 181   }
 182   // Otherwise, the latest supported version is recommended.
 183   else {
 184     $versions = array_keys($library['versions']);
 185     usort($versions, 'version_compare');
 186     $versions = array_reverse($versions);
 187     $version = $versions[0];
 188     $items[] = t('Download version %version of the library <a href="@download-url">here</a>.', array(
 189       '%version' => $version,
 190       '@download-url' => $library['download url'],
 191     ));
 192   }
 193   // 2. Unpack it.
 194   $items[] = t('If the library is an archive, i.e. if the file ending is for example <em>.tar.gz</em> or <em>.zip</em>, unpack it.');
 195   // 3. Create the libraries folder.
 196   $items[] = t('In the %library-directory directory of your Drupal installation create a %library directory.', array(
 197     '%library-directory' => 'sites/all/libraries',
 198     '%library' => $library['machine name'],
 199   ));
 200   // 4. Upload it.
 201   // If the library has variant-independent files, give the user the
 202   // location of an example file to check his filesystem against.
 203   if ($directory_layout = libraries_admin_directory_layout($library)) {
 204     $items[] = t('Upload the whole library (which can consist of multiple directories) into the newly created %library-path directory. The following files and directories should be contained in that directory: !directory-layout', array(
 205       '%library-path' => 'sites/all/libraries/' . $library['machine name'],
 206       '!directory-layout' => drupal_render($directory_layout),
 207     ));
 208   }
 209   else {
 210     $items[] = t('Upload the whole library (which can consist of multiple directories) into the newly created %library-path directory.', array(
 211       '%library-path' => 'sites/all/libraries/' . $library['machine name'],
 212     ));
 213   }
 214   // 5. Reload.
 215   $items[] = t('<a href="">Reload</a> the page. If successful, you should see status information about this library.');
 216
 217   $build['steps'] = array(
 218     '#theme' => 'item_list',
 219     '#items' => $items,
 220     '#type' => 'ol'
 221   );
 222
 223   return $build;
 224 }
 225
 226
 227 /**
 228  * Returns instructions for dealing with an undetected library.
 229  *
 230  * @param array $library
 231  *   A library information array.
 232  *
 233  * @return array
 234  *   A renderable array containing the instructions.
 235  */
 236 function libraries_admin_instructions_undetected($library) {
 237   $build = array();
 238   // Re-check location.
 239   // @todo Avoid usage of <br> elements.
 240   $build['instruction']['#markup'] = t('Check that the whole library is located at %library-path.', array(
 241       '%library-path' => $library['library path'],
 242     )) . '<br>';
 243   // If the library has variant-independent files, give the user the
 244   // exact location of the files to check against.
 245   // @todo It should be possible to display even variant-specific files
 246   //   in case the variant is installed, but libraries_detect() does not
 247   //   detect variants if the library version cannot be detected.
 248   if ($directory_layout = libraries_admin_directory_layout($library)) {
 249     $build['directory_layout'] = $directory_layout;
 250     $build['directory_layout']['#prefix'] = t('The following files and directories should be contained in that directory:');
 251   }
 252
 253   // If the library is placed correctly the library information is
 254   // incorrect.
 255   // This switch could be avoided by using $library['info type'], but that would
 256   // hinder properly translating these strings.
 257   $build['reload']['#markup'] = t('If you have moved any files, <a href="">reload</a> the page. If successful, you should see status information about this library.') . '<br>';
 258   $build['notice']['#markup'] = t('If the files are placed correctly and the version can still not be detected, the library information is incorrect.') . '<br>';
 259
 260   $provider = libraries_admin_get_provider($library);
 261   switch ($library['info type']) {
 262     case 'module':
 263       $build['contact']['#markup'] = t('Contact the maintainer of the %module module to correct this.', array(
 264           '%module' => $provider,
 265         )) . '<br>';
 266       break;
 267
 268     case 'theme':
 269       $build['contact']['#markup'] = t('Contact the maintainer of the %theme theme to correct this.', array(
 270           '%theme' => $provider,
 271         )) . '<br>';
 272       break;
 273
 274     case 'info file':
 275       $build['contact']['#markup'] = t('Contact the maintainer of the %info-file info file to correct this.', array(
 276           '%info-file' => $provider,
 277         )) . '<br>';
 278       break;
 279   }
 280   return $build;
 281 }
 282
 283
 284 /**
 285  * Returns instructions for dealing with an unsupported library.
 286  *
 287  * @param array $library
 288  *   A library information array.
 289  *
 290  * @return array
 291  *   A renderable array containing the instructions.
 292  */
 293 function libraries_admin_instructions_unsupported($library) {
 294   $build = array();
 295   $items = array();
 296
 297   // Either download a different version of the library...
 298   $versions = array_keys($library['versions']);
 299   usort($versions, 'version_compare');
 300   $versions = array_reverse($versions);
 301   $version = $versions[0];
 302   $build['instruction']['#markup'] = t('Please install version %version of the library by following the following steps:',
 303     array(
 304       '%version' => $version,
 305     ));
 306   // 1. Delete the old library.
 307   $items[] = t('Delete the entire contents of the %library-path directory.',
 308     array(
 309       '%library-path' => $library['library path'],
 310     ));
 311   // 2. Download the new library.
 312   $items[] = t('Download version %version of the library <a href="@download-url">here</a>.',
 313     array(
 314       '%version' => $version,
 315       '@download-url' => $library['download url'],
 316     ));
 317   // 3. Unpack it.
 318   $items[] = t('If the library is an archive, i.e. if the file ending is for example <em>.tar.gz</em> or <em>.zip</em>, unpack it.');
 319   // 4. Upload the new library.
 320   // If the library has variant-independent files, give the user the
 321   // location of an example file to check his filesystem against.
 322   if ($directory_layout = libraries_admin_directory_layout($library)) {
 323     $items[] = t('Upload the new files into the %library-path directory. The following files and directories should be contained in that directory: !directory-layout',
 324       array(
 325         '%library-path' => $library['library path'],
 326         '!directory-layout' => drupal_render($directory_layout),
 327       ));
 328   }
 329   else {
 330     $items[] = t('Upload the new files into the %library-path directory.',
 331       array(
 332         '%library-path' => $library['library path'],
 333       ));
 334   }
 335   // 5. Reload.
 336   $items[] = t('<a href="">Reload</a> the page. If successful, you should see status information about this library.');
 337   $build['steps'] = array(
 338     '#theme' => 'item_list',
 339     '#items' => $items,
 340     '#type' => 'ol',
 341   );
 342   // ...or contact the maintainer of the library information.
 343   $provider = libraries_admin_get_provider($library);
 344   switch ($library['info type']) {
 345     case 'module':
 346       $build['contact']['#markup'] = t('If you are bound to version @version of the library, ask the maintainer of the %module module to provide support for it.', array(
 347           '@version' => $library['version'],
 348           '%module' => $provider,
 349         )) . '<br>';
 350       break;
 351
 352     case 'theme':
 353       $build['contact']['#markup'] = t('If you are bound to version @version of the library, ask the maintainer of the %theme theme to provide support for it.', array(
 354           '@version' => $library['version'],
 355           '%theme' => $provider,
 356         )) . '<br>';
 357       break;
 358
 359     case 'info file':
 360       $build['contact']['#markup'] = t('If you are bound to version @version of the library, ask the maintainer of the %info-file info file to provide support for it.', array(
 361           '@version' => $library['version'],
 362           '%info-file' => $provider,
 363         )) . '<br>';
 364       break;
 365   }
 366   return $build;
 367 }
 368
 369 /**
 370  * Returns the directory layout of the library, if possible.
 371  *
 372  * The result of this function can help users to verify that they have uploaded
 373  * the library to the correct location.
 374  *
 375  * @param array $library
 376  *   A library information array.
 377  *
 378  * @return array|false
 379  *   A renderable array containing the directory layout of the library or FALSE
 380  *   if a directory layout could not be generated.
 381  */
 382 function libraries_admin_directory_layout(array $library) {
 383   $build = array(
 384     '#theme' => 'item_list',
 385     '#type' => 'ul',
 386     '#items' => array(),
 387   );
 388
 389   $items = &$build['#items'];
 390   if ($library['path']) {
 391     $items = &libraries_admin_path_to_tree($items, $library['path']);
 392   }
 393   foreach (array('js', 'css', 'php') as $type) {
 394     if (!empty($library['files'][$type])) {
 395       $files = array_keys($library['files'][$type]);
 396       foreach ($files as $file) {
 397         // Skip JavaScript settings.
 398         if (is_int($file)) {
 399           continue;
 400         }
 401
 402         $children = &$items;
 403         libraries_admin_path_to_tree($children, $file);
 404       }
 405     }
 406   }
 407   return $build['#items'] ? $build : FALSE;
 408 }
 409
 410 /**
 411  * Converts a file path into a tree structure for use in an item list.
 412  *
 413  * For example, the path 'foo/bar/baz' will be converted into the tree structure
 414  * represented by the following list:
 415  * - foo
 416  *   - bar
 417  *     - baz
 418  *
 419  * The $items array that is modified by reference or returned (see below) can
 420  * be used as the 'items' variable for theme_item_list().
 421  *
 422  * This function modifies passed-in $items array, so that multiple paths can
 423  * be placed into the same tree structure easily.
 424  *
 425  * @code
 426  *   $items = array();
 427  *   foreach ($paths as $path) {
 428  *     libraries_admin_path_to_tree($items, $path);
 429  *   }
 430  * @endcode
 431  *
 432  * It also returns the last item by reference, so that it can also be used to
 433  * traverse into a sub-structure and add further children there.
 434  *
 435  * @code
 436  *   $items = array();
 437  *   $children = &libraries_admin_path_to_tree($items, $path);
 438  *   foreach ($sub_paths as $sub_path) {
 439  *     libraries_admin_path_to_tree($children, $sub_path);
 440  *   }
 441  * @endcode
 442  *
 443  * @param array $items
 444  * @param string $path
 445  *
 446  * @return array
 447  */
 448 function &libraries_admin_path_to_tree(array &$items, $path) {
 449   $part = strtok($path, '/');
 450   while ($part) {
 451     if (!isset($items[$part])) {
 452       $items[$part] = array(
 453         'data' => $part,
 454         'children' => array(),
 455       );
 456     }
 457     $items = &$items[$part]['children'];
 458     $part = strtok('/');
 459   }
 460
 461   return $items;
 462 }
 463
 464 /**
 465  * Sorts libraries by name.
 466  *
 467  * This function can be used as a callback for usort() or uasort().
 468  *
 469  * @param array $a
 470  *   The first library information array.
 471  * @param array $b
 472  *   The second library information array.
 473  *
 474  * @return int
 475  *   Returns -1 if $a is considered smaller than $b, 1 if $a considered greater
 476  *   than $b and 0 if $a and $b are considered equal.
 477  *
 478  * @see strnatcasecmp()
 479  * @see usort()
 480  * @see uasort()
 481  */
 482 function libraries_admin_sort_title(array $a, array $b) {
 483   return strnatcasecmp($a['name'], $b['name']);
 484 }
 485
 486 /**
 487  * Returns the library's provider.
 488  *
 489  * The provider can be a module, a theme, or an info file.
 490  *
 491  * @param array $library
 492  *   A library information array.
 493  *
 494  * @return string
 495  *   The provider.
 496  */
 497 function libraries_admin_get_provider($library) {
 498   $provider = '';
 499
 500   switch ($library['info type']) {
 501     case 'module':
 502     case 'theme':
 503       $info = system_get_info($library['info type'], $library[$library['info type']]);
 504       $provider = $info['name'];
 505       break;
 506
 507     case 'info file':
 508       $provider = basename($library['info file']);
 509       break;
 510   }
 511
 512   return $provider;
 513 }
 514
 515 /**
 516  * Returns the library's provider and provider type.
 517  *
 518  * The provider type is either 'module', 'theme', or 'info file'.
 519  *
 520  * @param array $library
 521  *   A library information array.
 522  *
 523  * @return string
 524  *   The provider and provider type.
 525  */
 526 function libraries_admin_get_provider_with_type($library) {
 527   $provider = libraries_admin_get_provider($library);
 528   $provider_with_type = '';
 529
 530   // This switch could be avoided by using $library['info type'], but that would
 531   // hinder properly translating these strings.
 532   switch ($library['info type']) {
 533     case 'module':
 534       $provider_with_type = t('%module module', array('%module' => $provider));
 535       break;
 536
 537     case 'theme':
 538       $provider_with_type = t('%theme theme', array('%theme' => $provider));
 539       break;
 540
 541     case 'info file':
 542       $provider_with_type = t('%info-file info file', array('%info-file' => $provider));
 543       break;
 544   }
 545
 546   return $provider_with_type;
 547 }