利用 Libraries API 向 Drupal 项目中添加JS库

Wed, 05 Aug 2015 10:32:19 +0800

原文：Adding JS libraries to a Drupal project with Libraries API

作为一个前端开发者，我经常需要为了前端的一些需求向项目中加入 JavaScript 库。在 Drupal 中，有很多种方式来完成这一任务，最近我开始注意到一个模块：Libraries API，它为 Drupal 开发者提供了一个稳定的方法来添加各种库。

一个 Library 是一组代码，通常是 CSS 和 JS，有时候也会是一组 PHP，或者一些其他什么东西。一般来说，这些库并不是为 Drupal 设计的。

过去，我直接把 JS 库加入到我的主题之中，接下来使用 drupal_add_js() 把 JS 加入到页面。这意味着这个库同主题被绑定在一起。如果我想要在模块中使用这个库，我必须要知道这个主题的名字——用 drupal_get_path()。这很明显是个混蛋办法，他基本上断绝了模块化和代码复用的可能性。

另一个添加 JS 库的方法就是使用模块进行加载。这种方法的不足在于，JS 库常需要通过 Drupal UI 来配置，配置能力有时会影响库的能力，同步更新也不容易保证。在多数情况下，这种方式可以使用 Libraries API 来实现。

使用这个库是很容易的。当然，最好是阅读一下完整的文档，不过想随便试试，只要几行代码就能搞定。

快速入门

安装 Libraries API

如果你在使用Drush，那么很简单了：

$ drush dl libraries

下一步，建立一个目录 sites/all/libraries。如果你没有使用Drush，那么在官方网站进行下载安装即可。

向`sites/all/libraries`中添加库

下载一个库，然后把他添加到 sites/all/libraries 目录中。例如，我在使用 FlexSlider，用来在我的项目中实现幻灯片效果。要添加这个库，我下载了 flexslider，然后把它加入我的drupal项目的 sites/all/libraries/flexslider 中。

创建一个小模块，让 Libraries API 了解这个库

在一个自定义模块中，使用 hook_libraries_info 来启用这个库。一个库被注册之后，他就可以被其他模块或主题使用了。

/**
  * Implements hook_libraries_info().
  */
function MYMODULE_libraries_info() {
  $libraries = array();
  $libraries['flexslider'] = array(
    'name' => 'FlexSlider',
    'vendor url' => 'http://flexslider.woothemes.com/',
    'download url' => 'https://github.com/woothemes/FlexSlider/zipball/master',
    'version arguments' => array(
      'file' => 'jquery.flexslider-min.js',
      // jQuery FlexSlider v2.1
      'pattern' => '/jQuery FlexSlider v(\d+\.+\d+)/',
      'lines' => 2,
    ),
    'files' => array(
      'js' => array(
        'jquery.flexslider-min.js',
      ),
    ),
  );

  return $libraries;
}

这个过程有个心得就是，提供一个版本参数或者实现版本回调是很有必要的。hook_libraries_info() 的文档中提到，这两个都是可选的项目，不过至少要提供一个，否则该库无法被载入。如果对版本的事情不太在意，可以使用一个替身方法来实现 version 回调：

/**
* Implements hook_libraries_info().
*/
function MYMODULE_libraries_info() {
  $libraries = array();
  $libraries['my_library'] = array(
    // Etc etc.
    'version callback' => 'short_circuit_version',
  );

  return $libraries;
}

/**
* Short-circuit the version argument.
*/
function short_circuit_version() {
  return TRUE;
}

在页面中调用新引入的库

在这个例子中，我想要在一个特定的 View 中载入 FlexSlider。所以这里我们实现一个 Views 的 Hook。注意这里如何把 Hook 到指定的 Views:

/**
  * Implements hook_preprocess_views_view().
  */
function MYTHEME_preprocess_views_view(&$vars) {

  // 去掉注释，查看可用的变量
  // This requires http://drupal.org/project/devel to be installed.
  // dpm($vars['view']->name, 'view name');

  // 根据View ID调用指定方法
  if (isset($vars['view']->name)) {
    $function = 'preprocess_views_view__' . $vars['view']->name;
    if (function_exists($function)) {
      $function($vars);
    }
  }
}

/**
  * Implements preprocess_views_view__VIEW().
  */
function preprocess_views_view__YOURHOOK(&$vars) {
  $display_id = $vars['display_id'];
  $classes = &$vars['classes_array'];
  $title_classes = &$vars['title_attributes_array']['class'];
  $content_classes = &$vars['content_attributes_array']['class'];

  // Uncomment the lines below to see variables you can use to target a view.
  // This requires http://drupal.org/project/devel to be installed.
  // dpm($vars['view']->name, 'view name');

  switch ($display_id) {

    // 载入FlexSlider库
    case 'page':
      libraries_load('flexslider');
      break;
  }
}

使用

现在 FlexSlider 已经载入，就可以在这个 View 中使用了：

(function ($) {
  $(window).load(function() {

    $('.slideshow').flexslider({
      animation: "slide",
      controlNav: false,
      namespace: 'slide-',
      selector: '.slide-list > .slide-list-item'
    });

  }); // end window.load
})(jQuery);

你可以看到，Libraries API 提供了一种便捷的方式来进行 JavaScript 管理。

译者按：

这种方法还是蛮不方便的，更简单的方式就是，直接手写info文件，例如我们要载入一个 jsonview 的库

把 json view 的内容解压到 all/libraries/jsonview 目录中。

新建文件 jsonview.libraries.info

name = Json View
machine name = jsonview
description = json view plugins for jQuery
version = 1.2.0
files[js][] = jquery.jsonview.js
files[css][] = jquery.jsonview.css

利用 drush libraries-list 命令，查看 Libraries 载入结果：

名字         状态            版本       Variants  Dependencies
 jsonview   OK            1.2.0    -         -

另附 tcpdf 库的 libraries.info 内容：

name = TCPDF for PHP
machine name = tcpdf
description = tcpdf
version = 6.0.093
files[php][] = tcpdf.php

libraries | 伪架构师