作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

我们在第2章中已经看到，当我们编写的模块需要创建一个或者多个数据库表来存储信息时，创建和维护表结构的指令都放在了模块的install文件中。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

这个字段是用来存储整数的，比如节点id、vid。如果unsigned键为TRUE的话，那么将不允许使用负整数。Node表中vid字段就是采用的这种类型：

'vid' => array(

  'description' => 'The current {node_revision}.vid version identifier.',

  'type' => 'int',

  'unsigned' => TRUE,

  'not null' => TRUE,

  'default' => 0,

),

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

一个序列字段是用来保存自增数字的。例如，当添加一个节点时，node表中的nid字段将会自增。序列字段必须索引；通常会把它作为主键进行索引。

'nid' => array(

  'description' => 'The primary identifier for a node.',

  'type' => 'serial',

  'unsigned' => TRUE,

  'not null' => TRUE,

 ),

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

浮点数字是用来存储浮点数据类型的。对于浮点数字来说，tiny, small, medium, 和normal型浮点一般是没有区别的；另外，big型浮点用来声明双精度字段。Ubercart的uc_products表中weight字段用到了这一个类型。

 'weight' => array(

  'description' => 'Physical weight.',

  'type' => 'float',

  'not null' => TRUE,

  'default' => 0.0,

),

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

数字数据类型允许你声明数字的精度和小数位数。精度指的是数字的有效数字位数。小数位数指的是小数点右边的数字位数。例如，123.45的精度为5，小数位数为2。这里不使用size键。到目前为止，Drupal核心中还没有用到该字段。Ubercart的uc_products表中list_price字段用到了这一个类型。

'list_price' => array(

  'description' => 'Suggested retail price.',

  'type' => 'numeric',

  'precision' => 16,

  'scale' => 5,

  'not null' => TRUE,

  'default' => 0.0,

),

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

二进位大型对象数据类型用于存储二进制数据。二进位数据包括音乐，图片，或者视频。Size的可选值有normal 和big。Field模块的field_config表中data字段就是使用的这种类型，用来存储序列化的数据。

'data' => array(

  'type' => 'blob',

  'size' => 'big',

  'not null' => TRUE,

  'serialize' => TRUE,

  'description' => 'Serialized data containing the field properties that do not warrant a dedicated column.',

),

表.模式定义中的Type和Size键与本地数据库类型的对应关系

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

 我们在前面定义了block_morelink这个数据库表。但是有人在使用的过程中，出现错误，并且在我们的项目页面提交了bug，http://drupal.org/node/1159446，“Install Exception on new site: Syntax error or access violation: 1071 Specified key was too long”。这个问题的原因是，url，title的长度加在一起超过了主键的限制。此时我们需要修改数据库模式的定义。

    将block_morelink_schema中的主键

'primary key' => array('module', 'delta', 'url', 'title'),

    修改为：

'primary key' => array('module', 'delta'),

对于那些已经安装了这个模块的用户来说，我们需要为其提供一个升级路径，代码如下：

/**

 * change 'primary key' to array('module', 'delta').

 */

function block_morelink_update_7000(&$sandbox) {

  db_drop_primary_key('block_morelink');

  db_add_primary_key('block_morelink', array('module', 'delta'));

}

    在这里我们实现了钩子函数hook_update_N(&$sandbox)，由于这是block_morelink模块的第一个更新函数，所以我们将这里的N设置为了7000，那么第二个更新函数就应该是7001了。在钩子函数中，我们首先删除了原有的主键，接着添加了新版的主键。Drupal会追踪模块模式的当前版本，在运行完这个更新以后，该模块的模式版本就设置为了7000，这一信息存储在system表的schema_version列中。

    我们再看一个例子，这段代码摘自于feeds模块的install文件：

function feeds_update_7100(&$sandbox) {

  $spec = array(

    'type' => 'text',

    'size' => 'big',

    'not null' => FALSE,

    'description' => 'State of import or clearing batches.',

    'serialize' => TRUE,

  );

  db_change_field('feeds_source', 'batch', 'state', $spec);

  $spec = array(

    'type' => 'text',

    'size' => 'big',

    'not null' => FALSE,

    'description' => 'Cache for fetcher result.',

    'serialize' => TRUE,

  );

  db_add_field('feeds_source', 'fetcher_result', $spec);

}

    在这个更新中，首先是将feeds_source中的字段batch重命名为了state，接着添加了一个新的字段fetcher_result。注意这里面分别用到了db_change_field和db_add_field。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

Drupal在安装过程中，一般将数据库表的创建，委托给drupal_install_schema()函数；而drupal_install_schema()负责从模块的schema钩子中获取模式定义，转换为具体数据库上的语法，最后创建相应的表结构。我们回顾一下，第二章中，我们创建的模式：

/**

 * Implements hook_schema().

 */

function block_morelink_schema() {

  $schema['block_morelink'] = array(

    'description' => 'Stores more link path.',

    'fields' => array(

      'module' => array(

        'type' => 'varchar',

        'length' => 64,

        'not null' => TRUE,

        'description' => "The block's origin module, from {block}.module.",

      ),

      'delta' => array(

        'type' => 'varchar',

        'length' => 32,

        'not null' => TRUE,

        'description' => "The block's unique delta within module, from {block}.delta.",

      ),

      'url' => array(

        'type' => 'varchar',

        'length' => 255,

        'not null' => TRUE,

        'description' => "The more link url of a block.",

      ),

      'title' => array(

        'type' => 'varchar',

        'length' => 255,

        'not null' => TRUE,

        'description' => "The more link title of a block.",

      ),

    ),

    'primary key' => array('module', 'delta', 'url', 'title'),

    'indexes' => array(

      'url' => array('url'),

    ),

  );

  return $schema;

}

这个模式定义描述了block_morelink表，它包含4个varchar类型的字段。它还定义了一个联合主键，为url定义了一个普通索引。注意，在字段描述中，引用另一个表中的字段时，需要为其使用花括号。这样模式模块（参看下一节）可以为表的描述构建方便的超链接。

    hook_schema为模块定义的每一个数据库表，返回一个带有键的数组。在该数组中，可以使用以下键：

· 'description':一个纯文本字符串，用来描述这个表及其目的。如果这里引用了其它表，那么需要将其放在花括号中。例如，node_revisions表的描述字段包含“为每一个{node}，存储每个修订本的标题和正文”。

· 'fields':一个关联数组，用来描述数据库表的列。它的定义仍然是一个关联数组，里面可以使用以下参数：

· 'description': 一个纯文本字符串，用来描述这个字段及其目的。如果这里引用了其它表，那么需要将其放在花括号中。例如，节点表的vid字段的描述包括“总是为这个字段保存最大的（最新的）{node_revision}.vid的值”。

· 'type': 通用的数据类型有：'char'、 'varchar'、 'text'、'blob'、'int'、 'float'、 'numeric'、 'serial'。大多数类型会映射到对应数据库引擎上的具体数据库类型。对于自增字段，需要使用'serial'。在MySQL上，这就会转换为'INT auto_increment'。

· 'mysql_type', 'pgsql_type', 'sqlite_type',等等：如果你需要的类型，没有包含在前面所列的内置支持的数据类型列表中，那么你可以为每个后台的数据库指定一个类型。在这种情况下，你就用不到type参数了，但是你需要注意，对于有些数据库，如果你没有单独为其指定可用的类型，那么你的模式在该类型的数据库上将无法运行。可行的解决办法是使用"text"类型作为一个回退。

· 'serialize'：一个布尔值，用来指示该字段是否将存储为序列化的字符串。 

· 'size':数据的大小，可选值有：'tiny'、'small'、'medium'、'normal'、'big'。这个用来提示该字段可以存储的最大值，以及用来判定将会使用数据库引擎的哪个具体的数据类型；例如，MySQL上，TINYINT vs. INT vs. BIGINT。默认为'normal'，表示选择基础类型，比如，在MySQL上，INT、VARCHAR、 BLOB等等。不是所有的大小，都适用于所有的数据类型。对于可用的联合情况，可参看DatabaseSchema::getFieldTypeMap()。

· 'not null':如果为true，那么在这个数据库中，就不允许存在NULL值；默认为false。

· 'default':字段的默认值。这里区别PHP的类型：'', '0', 和 0表示不同含义。如果你为一个'int'类型的字段指定默认值为'0'，此时它将不能正常工作，因为这里的'0'是一个字符串，而不是一个整数。

· 'length': 'char'、'varchar'、 'text'字段类型的最大长度。对于其它字段类型，将忽略这个参数。

· 'unsigned':布尔值，用来指示'int'、 'float'、'numeric'类型的字段是否可以包含符号。默认为FALSE。对于其它字段类型，将忽略这个参数。

· 'precision', 'scale':用于'numeric'类型的字段，用来表示数字的精度和保留的小数位数。这两个值都是必须的。对于其它字段类型，将忽略这两个参数。

    对于所有的类型，只有'type'是必须的，其它是可选的；对于'numeric'类型，除了'type'是必须的以外，'precision'和'scale'也是必须的。

· 'primary key':一个数组，里面包含一个或多个字段的键名，用来表示数据库表的主键。

· 'unique keys':包含唯一键的关联数组。它里面包含一个或多个字段的键名，用来表示数据库表的唯一键。

· 'foreign keys': 表关联的关联数组。它里面包含被引用表的名字，和一个包含对应列的数组。对应列的定义使用键值对的形式（'source_column' => 'referenced_column'）。

· 'indexes': 包含索引的关联数组。它里面包含一个或多个字段的键名，用来表示数据库表的一个索引。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

现在你可能会想，花这么大的功夫，创建一个这么复杂的数组，来向Drupal描述我们的表结构，是不是有点得不偿失啊？当你熟悉了这些语法结构以后，大多数的代码都是拷贝来，拷贝去，实际上你并不需要记忆太多，这非常类似于我们写的八股文。其次，存在第三方的模块，帮我们干这些脏活，这就是Schema（模式）模块，它的下载地址为：http://drupal.org/project/schema。下载了模块，将其启用。导航到“管理 〉结构 〉Schema”，点击Inspect（检查）标签，在这里，我们可以看到所有数据库表的模式定义。如果你为你的数据库表准备好了SQL脚本，那么使用模式模块，它就可以帮你自动生成模式定义，接着将其复制粘贴到你的.install文件中就可以了。

提示 你一般很少需要从头编写一个模式定义。一般情况下，你可以拷贝已有的模式，以此为基础定义自己的模式。或者，你可以使用已有的表，使用模式模块的Inspect（检查）标签，让它帮你创建模式定义。

模式模块还允许你查看任意模块的模式。如图所示，在模式模块中显示了block_morelink模块的模式。

图 4-1.模式模块显示了block_morelink模块的模式。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

在模式定义中声明的字段类型，将会映射成具体数据库中的本地字段类型。例如，一个size为tiny的整数字段将映射为MySQL中的TINYINT字段，或者PostgreSQL中的smallint字段。我们以mysql为例，看看实际的映射，在includes/database/mysql/schema.inc文件中，类DatabaseSchema_mysql中的公共方法getFieldTypeMap()，列出了对应的映射关系。

  public function getFieldTypeMap() {

    …

    static $map = array(

      'varchar:normal'  => 'VARCHAR',

      'char:normal'     => 'CHAR',

      'text:tiny'       => 'TINYTEXT',

      'text:small'      => 'TINYTEXT',

      'text:medium'     => 'MEDIUMTEXT',

      'text:big'        => 'LONGTEXT',

      'text:normal'     => 'TEXT',

      'serial:tiny'     => 'TINYINT',

      'serial:small'    => 'SMALLINT',

      'serial:medium'   => 'MEDIUMINT',

      'serial:big'      => 'BIGINT',

      'serial:normal'   => 'INT',

      'int:tiny'        => 'TINYINT',

      'int:small'       => 'SMALLINT',

      'int:medium'      => 'MEDIUMINT',

      'int:big'         => 'BIGINT',

      'int:normal'      => 'INT',

      'float:tiny'      => 'FLOAT',

      'float:small'     => 'FLOAT',

      'float:medium'    => 'FLOAT',

      'float:big'       => 'DOUBLE',

      'float:normal'    => 'FLOAT',

      'numeric:normal'  => 'DECIMAL',

      'blob:big'        => 'LONGBLOB',

      'blob:normal'     => 'BLOB',

    );

    return $map;

  }

  'not null' => TRUE,

  'default' => '',

),

如果default键未被设置，并且not null键被设置为了FALSE，那么默认值将被设置为NULL。

Text

Text字段用于大块的文本。例如，node_type表中的description字段就是这种类型。Text字段可以不使用默认值。

'description' => array(

  'description' => 'A brief description of this type.',

  'type' => 'text',

  'not null' => TRUE,

  'size' => 'medium',

  'translatable' => TRUE,

 ),

    其中size的类型可以为tiny、small、medium、big、normal。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

文本型字段是用来包含文本的。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

Varchar，也就是变长字符字段；对于长度小于256字符的文本，通常使用这一字段类型。它的最大的字符长度，可以使用length键定义。MySQL中 varchar 字段的长度为0–255字符（MySQL 5.0.2 及更早版本）和0–65,535字符（MySQL 5.0.3及以后版本）；而PostgreSQL中varchar字段的长度则可以更大一些。

例如，node_chema中node表type字段的定义：

'type' => array(

  'description' => 'The {node_type}.type of this node.',

  'type' => 'varchar',

  'length' => 32,

  'not null' => TRUE,

  'default' => '',

 ),

如果default键未被设置，并且not null键被设置为了FALSE，那么默认值将被设置为NULL。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

Char字段是定长字符字段。该字段的字符长度，可以使用length键定义。MySQL中char字段的长度为0–255字符。Drupal核心中，我并没有找到char类型的实例。Ubercart模块中的uc_countries表的country_iso_code_2、country_iso_code_3字段用到这一类型：

'country_iso_code_2' => array(

  'description' => 'The two-character ISO country code.',

  'type' => 'char',

  'length' => 2,Edit summary

  'not null' => TRUE,

  'default' => '',

),

如果default键未被设置，并且not null键被设置为了FALSE，那么默认值将被设置为NULL。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

Text字段用于大块的文本。例如，node_type表中的description字段就是这种类型。Text字段可以不使用默认值。

'description' => array(

  'description' => 'A brief description of this type.',

  'type' => 'text',

  'not null' => TRUE,

  'size' => 'medium',

  'translatable' => TRUE,

 ),

    其中size的类型可以为tiny、small、medium、big、normal。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

数字型数据类型是用来存储数字的，它包括integer（整数）、serial（序列数）、 float（浮点数）、 和numeric（数字）类型。

     作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com。

Drupal从2001年诞生到现在，经过了不断的版本演化和市场检验以后，日趋成熟和完善。Drupal已经超越一个传统意义上的CMS范畴，越来越多的程序员把它做看作一个内容管理框架(CMF)，总之Drupal正在演化为一门平台性质的技术。我们可以从三个方面来理解Drupal：

Drupal是一个基于GPL协议开源的内容管理系统。Drupal7包含了CMS的各种标准功能。比如文章的发布、文件图片的管理、用户帐号管理、菜单导航、频道分类等等。我们使用Drupal，可以搭建各种网站，比如个人的博客，企业的宣传网站，B2C门户网站，视频网站。

Drupal是一个内容管理框架，它提供了各种方式，允许开发者使用可插拔的模块来定制Drupal的功能。Drupal的开发者和使用者，可以从drupal.org上面下载各种模块，来扩展现有的功能，并且可以按照Drupal的规范，自己开发模块以满足需求。

Drupal背后有一个开放的社区，Drupal的成功，与社区的活跃程度是分不开的。在2011年1月Drupal7发布时，全球有800多个社区成员向Drupal核心贡献了代码。有数以千计的开发者，向社区贡献了7000多个模块，还有更多的人，在测试、文档、用户支持、翻译等方面为Drupal作出了贡献。

    对于Drupal的理解，仁者见仁，智者见智。我们在这里，就不用过多的纠结于Drupal到底是一个CMS，还是一个CMF这样的争论了，我们只需要了解Drupal能够做什么，我们需要它做什么就可以了。Drupal把很多复杂的事情，简单化了；同时Drupal也把很多简单的事情，复杂化了。这也是我们为什么对Drupal又爱又恨的原因。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

我们首先来看一下，在Drupal中，都会用到哪些技术。

2.1 PHP

  Drupal使用的编程语言是PHP（http://php.net）。PHP是一个流行的、跨平台的、服务器端执行的脚本语言。所以熟悉PHP，对于学习Drupal开发很有帮助。但是这并不是说，熟悉PHP 是必须的，由于Drupal本身，在PHP的基础上，又做了大量的封装，很多功能只需要调用自己的API即可实现，所以其它语言的程序员，转学Drupal，并不比PHP程序员转学Drupal更加困难。

  因为PHP易于入门，所以大量的PHP代码都是由新手编写的。而新手的水平大家也知道，他们的代码总是存在这样或者那样的问题，这就给PHP的名声带来了比较坏的影响。不过， PHP也可以用于构建严谨的程序。Drupal核心中的所有代码都遵守了严格的编码规范(http://drupal.org/nodes/318)，通过开源，Drupal代码也经过了成千上万人的锤炼。对于Drupal来讲，PHP的入门门槛比较低，这就意味着有更多的人能够为Drupal贡献代码，通过开源，会有很多人对这些代码进行检查，这样就保证了代码的质量。

  最后，需要注意的是，Drupal7所需的最低PHP版本是PHP5.2。由于在PHP5.2及后续版本中，面向对象编程正占据着主流地位，因而尽管Drupal本身是面向过程的，但是Drupal核心中的一些子系统，以及很多第3方模块，都广泛采用了面向对象编程技术。

2.2 web服务器

    最常用的web服务器就数Apache了，所以一开始Drupal就对Apache提供了内置支持。当然，这并不是说，Drupal不能运行在其它web服务器上。随着Drupal的流行，对其它web服务器的支持，也越来越完善了，比如IIS、lighttpd、nginx。最近两年，在Drupal的高性能应用实践中，越来越多的Drupal程序员把Nginx作为首选服务器，用以提升性能。

   我们在本书中不会涉及太多与web服务器相关的知识。这里值得一提的是，在Drupal中，简洁URL用到了web服务器的相关设置。有关简洁URL的相关配置，可以参看相关的文档。

2.3 数据库

  最初，Drupal对MySQL提供了内置支持，在Drupal的后续版本中，增加了对PostgreSQL的支持。在Drupal7中，内置支持了MySQL、PostgreSQL、SQLite三个数据库系统。由于Drupal7的数据库API，是完全基于PHP5的PDO，而PDO能够支持各种各样的数据库，比如Oracle、SQL Server、DB2，所以通过第3方模块，就可以实现Drupal7对Oracle、SQL Server，DB2的支持。Drupal 对商业数据库的支持，能够让Drupal 在更广泛的领域中得以应用。

2.4操作系统

  操作系统位于Drupal相关技术堆栈的最下面的一层，由于Drupal是基于PHP编写的，而PHP语言也具有跨操作系统的特点，所以只要操作系统能够支持PHP，我们就可以使用它来运行Drupal。Windows，Linux，Mac OS等等，在这些主流的操作系统上，都可以运行Drupal。操作系统层，主要负责网站相关的最底层的任务，比如网络连接，文件的权限。如果你是在linux下面安装运行Drupal，你经常会遇到文件夹权限不可写，这样的权限问题。

  本书的作者，使用的是Vista操作系统，所用的环境是XAMPP，所有的代码都是在这个操作系统下面编写的，相信这些程序也能够应用于其它操作系统及相关环境下。

2.5 HTML，CSS，JavaScript

  从Drupal系统中最终返回给浏览器的是HTML，而在HTML中，CSS是用来定义页面样式的，JavaScript则是浏览器客户端的脚本语言。需要注意的是，Drupal对JavaScript的支持，是通过jQuery实现的。jQuery是一个优秀的轻量级的JavaScript框架 (压缩后只有21k) ，它兼容CSS3，还兼容各种浏览器。作为一个Drupal开发者，我们今后肯定会涉及到这三种技术。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

我们从drupal.org上下载最新的Drupal7版本，把它结压缩后，放到本地的web文档目录下，这是我们就会看到Drupal核心文件夹下的目录结构了。

               Drupal7核心的默认文件夹结构

    通过了解Drupal默认安装的目录结构，我们能够了解一些最佳实践，比如下载的第3方模块和主题的放置位置，以及如何拥有不同的Drupal安装轮廓。我们来进一步的了解一下Drupal的文件夹目录：

3.1 includes 

  这个文件夹下面包含了Drupal通用的函数库,比如ajax、批处理、表单API、数据库API、本地化API等等。这些通用函数库，是Drupal程序运行的基石。

3.2 misc

这个文件夹下面包含了JavaScript文件，和其它各种图标和图片文件。其中JavaScript文件包括jquery.js、jquery.form.js、jquery.cookie.js、drupal.js、ajax.j、jQuery UI等等。

3.3 modules

   这个文件夹下面包含了所有核心模块，一个模块对应一个文件夹，总共40个模块。最好不要乱动这个文件夹（以及除profiles和sites外的其它文件夹）下面的任何东西。对于第3方模块、主题，或者自定义的模块、主题，应该放到sites目录下。

3.4 profiles 

    这个文件夹下面包含一个站点的不同安装轮廓（profile）。Drupal7自带了两个profile，一个是标准化安装（standard），一个是最小化安装（minimal）。安装轮廓的主要目的是，用来自动的启用核心的或者第3方的模块，并作一些初始化设置。比如rszrama为了方便大家测试commerce模块，就提供了一个commercedev安装轮廓（https://github.com/rszrama/commercedev），使用这个profile，用户就能够方便的搭建一个电子商务测试站点。

3.5 scripts

    这个文件夹下面包含了许多脚本，这些脚本可用于语法检查、清理代码、从命令行运行Drupal、使用cron处理特定情况、以及运行单元测试等等。在Drupal自身程序运行过程中，调用不到这些脚本；这里面都是一些shell和Perl的实用脚本。

3.6 sites

    这个文件夹下面用来放置Drupal的配置文件、第3方模块与主题、自定义模块与主题等等。你从第3方模块库中下载的模块，通常都放在sites/all/modules/standard下面；而你自己编写的模块，则放在sites/all/modules/custom目录下面。我们对Drupal所进行的任何修改，基本上都放在这个文件夹下进行。

   在sites下面有一个名为default的文件夹，里面包含了Drupal默认配置文件--- default.settings.php。在Drupal安装过程中，系统将会基于你提供的数据库帐号信息和这个默认文件，为你自动创建一个settings.php文件。对于多站点安装，配置文件通常位于sites/www.example.com/settings.php。

    另外sites/default/files通常用作Drupal文件系统所在的目录。Web服务器需要具有这个子目录的读写权限。默认情况下，Drupal在安装时会自动为你创建这个文件夹，并检查是否设置了相应的权限。

3.7 themes：

   这个文件夹下面包含了Drupal的模板引擎和默认主题。这里的默认主题有bartik、garland、seven等等。你下载的第3方主题以及自己创建的主题，不能放在这个位置，而应该放在sites/all/themes目录下面。

3.8 authorize.php：

   这个PHP文件里面包含了运行认证文件操作的管理脚本。通过settings.php中的全局变量killswitch以及'administer software updates'权限，可以控制对这个文件中脚本的访问。

3.9 cron.php：

   这个PHP文件用于执行定时任务，比如清理过期的缓存数据，以及计算统计信息。Drupal7在运行定时任务时，首先会检查cron_key是否正确，从而避免cron.php被恶意的调用执行。

3.10 index.php：

   这个PHP文件是Drupal处理http请求的主入口程序。它就相当于一个路由器，用来将程序的执行控制权分发给合适的处理器上，而后者会输出相应的页面内容。

3.11 install.php： 

   这个PHP文件是Drupal安装器的主入口程序。

3.12 update.php：

    这个PHP文件是Drupal升级时的主入口程序。通过设置settings.php中的全局变量update_free_access，可以绕过升级时的权限检查。

3.13 xmlrpc.php： 

    这个PHP文件用来接收XML-RPC请求，如果你的网站没有用到XML-RPC，那么可以将这个文件从中删除。

3.14 robots.txt：

    这个文件是搜索引擎爬虫排除标准的默认实现。在这个文件中，你可以定义搜索引擎爬虫能够访问哪些页面，不能访问哪些页面。

  此外，.htaccess文件是apache的相关配置文件；而web.config则是IIS的配置文件，它是Drupal7中新增的一个文件。其余文件则是相关的文档文件。

　　作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

　　通过了解Drupal自身的文件夹结构，我们对Drupal有了初步的认识。我们还需要对Drupal中的常用概念，或者说专有术语，有更好的界定。这能够帮助我们更好的学习使用Drupal。常用的术语有模块、钩子、主题、节点、菜单、区块、字段、实体等等。Drupal相关术语不仅仅是这里所列的这么几个，还有更多的相关术语。有兴趣的读者，可以参看http://drupal.org/node/19828。

　　作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

　　Drupal是如何处理一个HTTP页面请求呢？如果对于这样的请求处理,我们能够理解其基本的流程结构，那么对于今后的学习,将会很有帮助。如果你想追踪Drupal的代码执行过程，那么首先可以搭建好调试环境，从index.php文件开始，逐步设置断点，这样就可以快速的了解Drupal的基本原理了。让我们以一个简单的例子，来分析一下常用请求的处理流程。假定一个注册用户访问我的站点http://zhupou.cn,并浏览文章“Drupal入围2008全球开源CMS大奖赛决赛”，也就是访问路径http://zhupou.cn/node/88（我这里假定zhupou.cn已经升级到Drupal7）。

    1、首先，我们启用了简洁URL，Web服务器收到请求后，会按照URL重写把用户看到的URL，转换为系统可以理解的URL，在这里就是将http://zhupou.cn/node/88 转换为了http://zhupou.cn/index.php?node/88。Apache，IIS，Nginx都支持URL重写。

    2、PHP开始执行Drupal的index.php文件，Drupal获取到内部路径“node/88”.

    3、Drupal启动完整地引导指令流程，完成资源的初始化，加载所有启用的模块后，将内部路径“node/88”映射到了节点模块的对应回调函数node_page_view上。

    4、节点模块执行node_page_view函数，经过node_page_view -à node_show à node_view_multipleànode_viewànode_build_content这样的持续回调,它从数据库中读取ID为88的节点，并将返回的数据封装成一个drupal_render可以识别的数组。在node_view，node_build_content函数中，先后触发了以下钩子函数：hook_field_prepare_view,、hook_field_formatter_prepare_view、hook_entity_prepare_view、hook_field_formatter_view、hook_node_view、hook_entity_view、hook_node_view_alter、hook_entity_view_alter。

    5、主题系统获取节点88的数据信息，并将其使用html代码进行封装，同时应用CSS。主题系统获取与节点88相关的其它页面元素数据信息，并分别将其使用html代码进行封装，同时应用CSS。

    6、Drupal完成所有的处理后，把最终封装好的HTML、CSS数据传送给用户的浏览器。浏览器将这些数据显示成web页面，呈现给最终用户。

    这里重点需要理解的就是Drupal的引导指令，和相关的钩子函数调用。让我们对这两点进一步的解释。

　　作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

　　首先我们需要做的是为模块起一个名字。原来我想到的名字是“more_link”名字，考虑到这个模块只用于区块系统，又改用“block_more_link”，打算使用这个名字的时候，忽然想到link本身是一个钩子（注：Drupal7中已取消这个钩子），这样我又改为了“block_morelink”，看来为模块起一个名字有时候也需要细心的考虑一下。为一个模块起一个名字，对于我们这些中文用户来说，还真的有点麻烦。

    模块的名字包含用户可读名字和机读名字两种，上面用到的“block_morelink”就是模块的机读名字，它在Drupal系统内部使用，只能使用字母、数字、下划线。

    接着，我们需要找个地方来放置这个模块。我们可以把这个模块放在核心模块所在的目录中去，不过这样的话，我们需要记住哪些是核心模块，哪些是我们自定义的模块，将来升级维护的时候会比较麻烦。按照Drupal的最佳实践，我们应该把它放在目录sites/all/modules下面，以将其与核心模块区分开来。

我们在sites/all/modules下面在创建一个名为custom的文件夹，专门用来放置我们自己定义的模块。同时创建一个standard文件夹，用于放置第3方模块。是否将sites/all/modules下面的模块分成两类分别存放，取决于开发者的习惯和项目的实际情况。如果项目用到的模块比较少，自定义模块只有一个，此时通常不分。如果项目比较大，用到的第3方模块和自定义的模块都比较多，为了方便，此时建议分开管理。

    然后我们在sites/all/modules/custom下面创建一个名为block_morelink的文件夹。在Drupal 中，一个模块通常对应于一个文件夹，里面包含这个模块的所有相关文件。通常包含的文件有info文件、module文件、install文件、inc文件。由于我们的模块，需要在数据库中创建一个表结构，首先让我们创建3个文件，里面不包含任何内容，分别为block_morelink.info、block_morelink.module、block_morelink.install。

   接着，让我们为info文件添加内容。

 作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

 info文件的作用是，为Drupal模块提供元数据信息，比如这个模块的用户可读名字、模块的描述、这个模块所依赖的模块。我们为block_morelink.info文件添加以下内容： 

name = 区块更多链接

description = 为所有的区块提供了一个更多链接

core = 7.x

dependencies[] = block

configure = admin/config/block/morelink

    根据上面的内容，我们可以看出来，info文件是一个纯文本文件，它与标准的ini配置文件非常类似。它的指令语法为：

name = value

    就是一组由等号分割的名值对。如果一个名字可以有多个值的话，那么可以使用类似数组的形式：

name[] = value

    让我们来看一下，这些内容的含义：第一条指令的意思是说，模块的名字为“区块更多链接”；第二条指令为我们声明了这个模块的描述，告诉用户这个模块是用来做什么的，name和description的值会显示在模块列表页面；第三条指令，告诉Drupal这个模块所适用的Drupal主版本，这里为7.x，Drupal主版本之间是不兼容的；第四条指令，表示这个模块依赖于block模块，如果block模块没有启用，那么我们的这个模块也就无法启用；第五条指令，用于告诉Drupal这个模块的配置页面链接，同样显示在模块列表页面。

                 图 模块启用后在模块列表页面上显示的内容

    如果我们需要在info文件添加注释，那么可以使用“;”，语法如下：

;files[] = morelink.module

;files[] = morelink.admin.inc

;files[] = morelink.install

    注意我们在上面的注释中，使用了files[]指令，它用来表示这个模块都包含哪些文件。在Drupal7中，实现了缓加载机制，用来提升Drupal的性能。最初设计的目标是，Drupal可以缓加载所有的PHP函数、类、接口。但是在Drupal7正式版发布时，只实现了类、接口的缓加载。所以files[]指令的具体含义，就是声明模块中有哪些文件里面包含php类、接口的代码。由于我们这个模块中，没有使用到PHP面向对象技术，也就没有包含任何PHP类、接口。所以我们完全可以把与这个指令相关的代码注释掉。

    除此之外，常用的还有package、php指令。package用来表示，这个模块放在哪个包下面，反映在模块列表页面，就是放在哪个fieldset下面。Drupal核心模块，都放在Core下面。如果没有声明package，那么系统会自动将模块放在Other包下面。php表示所需PHP的最小版本，Drupal所需PHP的最小版本是PHP5.2。如果你的模块代码中，用到了PHP6.0中的最新特性，此时你可以添加以下代码：

php = 6.0

    对于从drupal.org上下载的第3方模块，你通常还会看到以下信息：

; Information added by drupal.org packaging script on 2011-05-06

version = "7.x-1.0-alpha1"

core = "7.x"

project = "field_validation"

datestamp = "1304650916"

    这些信息是由drupal.org上的打包脚本添加的，用来声明模块的版本、项目名称、Drupal核心、此版本发布时的时间戳。注意这里使用了双引号。双引号，通常可用可不用。

    最后需要注意的是，我们这个文件中包含中文，所以我们必须把info文件的文本格式设置为UTF-8，否则在Drupal中，就无法正确的显示我们的文本。对于我们中文圈内的Drupal开发者，时常应该记着把info、module、inc、php文件的文本格式设置为UTF-8，这样可以避免很多不必要的编码错误。

    现在我们创建好了info文件，让我们为module文件中添加内容。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

我们在文件的开始处使用PHP的开始标签，接着添加了一段简洁的注释：

<?php

/**

 * @file

 * 让用户为区块添加一个更多链接.

 *

 * 在区块的配置页面,允许用户输入更多链接,在区块显示的时候,显示一个更多链接.

 */

    首先需要注意的是，PHP开始标签“<?php”的前面不要有任何空格以及任何字符，否则有可能带来不必要的麻烦，举个例子userpoints_nc的module文件中，“<?php”的前面带有了两个空格，结果导致RSS输出不能正常工作（参看http://drupal.org/node/1096746）。其次需要注意的是，module文件中不要使用php结束标签 “?>”;这个结束标签对于PHP来说是可选的，但在Drupal中，有可能导致文件的尾部空格问题(参看http://drupal.org/node/545)。

接着，让我们看一下Drupal中注释的写法。我们首先从/**开始，在接下来的每一行中，缩进一格并以*开头，最后以*/结束。指令@file表示它下面的文本，是一个给出这个文件用途的描述。可以使用模块api.module，将这些注释提取成API文档。接着空了一行，后面跟着一段更长的描述，它用来向其它程序员说明这个模块是做什么的。

    下面我们要做的就是编写模块的逻辑了。我们在前面讲过，我们这个模块目的是为区块添加一个“更多链接”属性。为此，我们首先需要让用户为区块输入这个“更多链接”，在什么地方输入呢？应该在区块的配置页面，以及区块的添加页面，在这两个页面允许用户输入“更多链接”。首先让我们以区块的配置页面为例，我们先来看看这个页面。

                       图2-1默认的区块配置页面

    我们看到这个配置页面里面包含了一个表单，如果在这个页面，能够有那么一个表单元素，允许我们输入这个区块所指向的更多链接，这样就完美了。然而这个默认页面，并没有为我们提供这样的表单元素，这个时候，对于很多刚刚接触Drupal的其它程序员来说，首先想到应该就是修改这个页面对应程序的源代码，直接将我们想要的表单元素加进来。这个时候，聪明一点的程序员，就会顺藤摸瓜，根据路径信息，或者页面里面表单元素的信息，就会找到这个页面对应的代码，这就是位于block模块中block.admin.inc里面的block_admin_configure函数。

function block_admin_configure($form, &$form_state, $module, $delta) {

  $block = block_load($module, $delta);

  $form['module'] = array(

    '#type' => 'value',

    '#value' => $block->module,

  );

  $form['delta'] = array(

    '#type' => 'value',

    '#value' => $block->delta,

  );

  // Get the block subject for the page title.

  $info = module_invoke($block->module, 'block_info');

  if (isset($info[$block->delta])) {

    drupal_set_title(t("'%name' block", array('%name' => $info[$block->delta]['info'])), PASS_THROUGH);

  }

  $form['settings']['title'] = array(

    '#type' => 'textfield',

    '#title' => t('Block title'),

    '#maxlength' => 64,

    '#description' => $block->module == 'block' ? t('The title of the block as shown to the user.') : t('Override the default title for the block. Use <em>!placeholder</em> to display no title, or leave blank to use the default block title.', array('!placeholder' => '<none>')),

    '#default_value' => isset($block->title) ? $block->title : '',

    '#weight' => -18,

  );

  // Module-specific block configuration.

  if ($settings = module_invoke($block->module, 'block_configure', $block->delta)) {

    foreach ($settings as $k => $v) {

      $form['settings'][$k] = $v;

    }

  }

  // Region settings.

  $form['regions'] = array(

    '#type' => 'fieldset',

    '#title' => t('Region settings'),

    '#collapsible' => FALSE,

    '#description' => t('Specify in which themes and regions this block is displayed.'),

    '#tree' => TRUE,

  );

….

$form['actions'] = array('#type' => 'actions');

  $form['actions']['submit'] = array(

    '#type' => 'submit',

    '#value' => t('Save block'),

  );

  return $form;

}

    这是一个表单API函数，现在我们还没有必要完全掌握表单API，我们只需要了解这个函数是用来定义表单元素的，在这里它将表单定义成为一个大的数组$form，而这个表单中的每一个元素，同样是一个由键值构成的数组。比如$form['settings']['title']，其定义如下：

$form['settings']['title'] = array(

    '#type' => 'textfield',

    '#title' => t('Block title'),

    '#maxlength' => 64,

    '#description' => $block->module == 'block' ? t('The title of the block as shown to the user.') : t('Override the default title for the block. Use <em>!placeholder</em> to display no title, or leave blank to use the default block title.', array('!placeholder' => '<none>')),

    '#default_value' => isset($block->title) ? $block->title : '',

    '#weight' => -18,

  );

    这里面，左边的'#type'、'#title'、'#maxlength'、'#description'、'#default_value'、'#weight'是表单元素的键名，右边是对应的值。'#type'用来设定这个表单元素的类型，这里是'textfield'，'#title'对应于这个表单元素的label，'#maxlength'用来限制这个表单元素的最大长度，'#description'是表单元素后面的描述；'#default_value'用来设定这个表单元素的默认值；'#weight'决定了这个表单元素在整个表单中的位置，默认为0，重量越小越靠前，这里的值为-18，表示这个元素应该靠前放置。上述代码，经过Drupal的表单系统，就会被转换为HTML对应的表单元素。

    我想对于很多刚刚接触Drupal的人来说，上来就学习表单API的相关知识，开始肯定吃不消。对于这个模块实例，我没有从实现hook_menu、hook_perm、hook_help这样简单的钩子开始讲解，主要是为了给大家呈现一个解决问题完整过程，希望让读者在学习Drupal api的同时，能够掌握解决问题的方法，另外就是想突出一下表单API在Drupal模块开发中的重要性，只有掌握了表单API，才能算的上真正熟悉了Drupal模块开发。

    如果我们在$form['settings']['title']下面，添加一个新的表单元素，用来让用户输入“更多链接”，也同样能够解决问题，但是这会带来更多的问题，比如Drupal版本升级了，从Drupal7.0升级到了Drupal7.2，此时如果你修改了源代码，升级到Drupal7.2以后，原有的改动都被替换掉了，除非你再次修改同样的代码，或者使用打补丁的方式。但是这些方式都是不足取的，对于我们这些普通的Drupal开发者来说，永远不要修改Drupal核心代码，这在Drupal中是不允许的。

    那么有读者就会问了，不在这里修改源代码，那在什么地方添加我们的表单元素？难道我们能够不修改Drupal核心代码，就能将想要的表单元素添加到这个页面？答案当然是可以的。Drupal将表单抽象成为了数组，这为表单定义、呈现、处理带来了极大的灵活性。Drupal在呈现表单时，为我们提供了两个钩子，用来修改表单，一个是hook_form_alter，另一个是hook_form_FORM_ID_alter。讲到这里，聪明一点的读者就会想到，通过实现这两个钩子函数，我们就可以向区块配置页面添加我们的“更多链接”表单元素了。

    但是这里使用哪个钩子呢？是同时需要实现两个钩子函数，还是只需要实现其中的一个就可以了？实际上，对于上面的两个钩子，在很多时候两者之间是通用的，我们在hook_form_alter中，可以修改多个表单，而在hook_form_FORM_ID_alter中只能修改一个表单，而从性能方面来看，hook_form_FORM_ID_alter的效率要稍微高一点，但是这点性能提升，绝对不会对你站点的性能带来显著的影响。

    经过前面的准备工作，我们知道我们应该在module文件中实现hook_form_FORM_ID_alter这个钩子函数。对于这个钩子函数，我们首先需要知道，这里面大写的FORM_ID是需要被替换成为实际的表单ID的，什么是表单ID？它通常就是定义表单的函数的名字，由于我们在前面找到了区块配置表单的对应函数block_admin_configure，所以这里的FORM_ID就应该被替换为block_admin_configure。

    让我们来定义我们的第一个钩子函数：

function block_morelink_form_block_admin_configure_alter(&$form, &$form_state){

  $default_morelink_url = '';

  $form['settings']['morelink_url'] = array(

    '#type' => 'textfield',

    '#title' => t('More Link url'),

    '#maxlength' => 255,

    '#description' => t('The More Link url of the block as shown to the user.') ,

    '#default_value' =>  $default_morelink_url,

    '#weight' => -17,

  );

}

    在这个钩子函数中，我们新增了一个表单元素$form['settings']['morelink_url']，我们可以通过这个表单元素来输入更多链接所指向的URL。

    对于一个链接，它通常包含2部分，一部分是链接文本，这里面我们可以使用“更多”这一固定文本就可以了；另一部分是链接指向的路径，就是前面我们所定义的；此外，还有一个重要的组成部分，那就是鼠标移到链接上，所显示的提示文本，这是我们目前所忽略的，但对于实际的SEO非常有用。尽管后者可有可无，让我们还是在这个钩子函数中，为其新增一个表单元素：

function block_morelink_form_block_admin_configure_alter(&$form, &$form_state){

  $default_morelink_url = '';

  $default_morelink_title = '';

  $form['settings']['morelink_url'] = array(

    '#type' => 'textfield',

    '#title' => t('More Link url'),

    '#maxlength' => 255,

    '#description' => t('The More Link url of the block as shown to the user.') ,

    '#default_value' =>  $default_morelink_url,

    '#weight' => -17,

  );

  $form['settings']['morelink_title'] = array(

    '#type' => 'textfield',

    '#title' => t('More Link title'),

    '#maxlength' => 255,

    '#description' => t('The More Link title of the block as shown to the user.') ,

    '#default_value' =>  $default_morelink_title,

    '#weight' => -17,

  );

}

    我们在解决问题的时候，很多时候并不能一步到位，比如这里新增的这个表单元素，我们就是出于SEO的考虑，而新增过来的。新增的这个表单元素，并不会为后续开发带来很多麻烦。启用这个模块，现在我们在区块的配置页面，就能够看到我们新增的两个表单元素了。如图2-2所示。

    我们在前面还提到区块的添加页面，这里也是一个表单页面，我们也需要为其新增两个同样的表单元素。我们找到区块的添加页面对应的函数block_add_block_form，同样位于block模块的block.admin.inc文件里面，代码如下：

function block_add_block_form($form, &$form_state) {

  return block_admin_configure($form, $form_state, 'block', NULL);

}

    这个函数相当简单，它直接把表单的定义工作委托给了block_admin_configure。我们在这里知道了这个表单的ID，block_add_block_form，尽管实际工作都是由block_admin_configure完成的，但是在这里，表单ID变了。因此我们需要在我们的模块中，为block_add_block_form定义钩子函数，代码如下：

function block_morelink_form_block_add_block_form_alter(&$form, &$form_state) {

  block_morelink_form_block_admin_configure_alter($form, $form_state);

}

                       图2-2 带有更多链接输入的区块配置页面

    我们也仿照着block_add_block_form，在我们的钩子函数block_morelink_form_block_add_block_form_alter中，我们将表单的修改工作，都委托给了block_morelink_form_block_admin_configure_alter，这就是我们前面定义好的钩子函数。我们再次打开区块的添加页面，就可以看到新增的两个表单元素了。

    接下来需要考虑的是，这个表单提交时，对于新增表单元素所提交的数据，我们如何处理？显然Drupal核心中的代码，并不知道我们新增了两个表单元素，所以核心部分是不会负责处理我们新增的这两个元素的，因此我们需要自己对这两个元素负责。Drupal允许我们在hook_form_FORM_ID_alter钩子函数中，追加新的表单验证函数和提交函数。我们分别追加一个验证函数和一个提交函数：

function block_morelink_form_block_admin_configure_alter(&$form, &$form_state){

  $default_morelink_url = '';

  $default_morelink_title = '';

  $form['settings']['morelink_url'] = array(

    '#type' => 'textfield',

    '#title' => t('More Link url'),

    '#maxlength' => 255,

    '#description' => t('The More Link url of the block as shown to the user.') ,

    '#default_value' =>  $default_morelink_url,

    '#weight' => -17,

  );

  $form['settings']['morelink_title'] = array(

    '#type' => 'textfield',

    '#title' => t('More Link title'),

    '#maxlength' => 255,

    '#description' => t('The More Link title of the block as shown to the user.') ,

    '#default_value' =>  $default_morelink_title,

    '#weight' => -17,

  );

  $form['#validate'][] = 'block_morelink_block_admin_configure_validate';

  $form['#submit'][] = 'block_morelink_block_admin_configure_submit';

}

    注意这里面$form['#validate']和$form['#submit']，它们是两个数组，里面分别包含了这个表单的验证函数集，和提交函数集。我们新增的验证函数和提交函数，通常并不影响已有的验证函数和提交函数，表单在验证阶段会调用它上面所有的验证函数，而在提交阶段，则会调用它上面所有的提交函数。

    我们在module文件中，建立这两个函数：

/**

 * Form validate handler for block configuration form.

 */

function block_morelink_block_admin_configure_validate($form, &$form_state){

  //Todo

}

/**

 * Form submit handler for block configuration form.

 */

function block_morelink_block_admin_configure_submit($form, &$form_state){

  //Todo

}

    在验证函数中，我们可以验证URL的有效性，但是在实际的开发应用中，这些验证并不是很重要，用户只需要自己输入有效的URL就可以了。所以我们暂时先不考虑这个验证函数。而在提交函数中，我们则需要把用户输入的信息保存到数据库中，显然我们现在还没有准备好用来存储数据的数据库表。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

模块中存储所用数据的常用方式，就是为这些数据创建一个单独的数据库表。当我们决定为模块创建数据库表结构时，应该问问自己：我们需要存储哪些数据？如果我们要对这个表进行查询，那么会用到哪些字段和索引？最后，还要考虑一下，将来对这个模块，有没有可能会作些扩展？

    首先让我们分析一下需要存储的数据。除了上面新增表单元素里面的信息外，我们还需要保存区块的ID信息，这样我们才能知道这个更多链接信息是属于哪个区块的。使用一个mysql的管理工具，比如phpmyadmin，我们打开Drupal的数据库结构，我们发现，在Drupal中，区块的ID是由模块名和delta值共同组成的。这样对于一个区块，我们需要保存4个值，分别为module、delta、url、title。另外我们需要为我们的数据库表起个名字，为了简单起见，就叫做block_morelink，和我们的模块名保持一致。

    我们表的SQL语句如下所示：

CREATE TABLE block_morelink (

  module varchar(64) NOT NULL,

  delta varchar(32) NOT NULL,

  url varchar(255) NOT NULL,

  title varchar(255) NOT NULL,

  PRIMARY KEY (module,delta,url,title),

)

我们可以把这段sql语句放到我们模块的README.txt文件中，这样我们就省事了。但是对于想要安装这个模块的其他用户来说，他们需要手工的使用上述SQL语句来创建数据库表，这样做会比较麻烦。实际上，在Drupal中，有更好的解决方式，我们知道，在启用核心模块时，Drupal能自动的创建相应的数据库表；我们可以使用Drupal的这一特性。我们在前面创建的install文件中，添加以下代码：

/**

 * Implements hook_schema().

 */

function block_morelink_schema() {

  $schema['block_morelink'] = array(

    'description' => 'Stores more link path.',

    'fields' => array(

      'module' => array(

        'type' => 'varchar',

        'length' => 64,

        'not null' => TRUE,

        'description' => "The block's origin module, from {block}.module.",

      ),

      'delta' => array(

        'type' => 'varchar',

        'length' => 32,

        'not null' => TRUE,

        'description' => "The block's unique delta within module, from {block}.delta.",

      ),

      'url' => array(

        'type' => 'varchar',

        'length' => 255,

        'not null' => TRUE,

        'description' => "The more link url of a block.",

      ),

      'title' => array(

        'type' => 'varchar',

        'length' => 255,

        'not null' => TRUE,

        'description' => "The more link title of a block.",

      ),

    ),

    'primary key' => array('module', 'delta', 'url', 'title'),

    'indexes' => array(

      'url' => array('url'),

    ),

  );

  return $schema;

}

在第一次启用block_morelink模块时，drupal会检查block_morelink.install文件，看里面是否实现了hook_schema钩子，它将读取hook_schema中所定义的数据库表结构模式，并将它们转化为了当前数据库的标准SQL语句。有关这方面的更多信息，可参看Schema API一章。如果一切顺利的话，这样就完成了数据库表的创建工作。让我们试验一下。由于我们在前面还没有创建数据库表的时候，就启用了该模块，所以我们需要重新安装一下这个模块，需要按照以下步骤进行重装：

1、导航到“管理 > 模块”，先将block_morelink模块禁用。

2、在管理界面“管理 > 模块”，找到”卸载”标签，点击这个标签，选择block_morelink模块，卸载。这样Drupal就会删除与这个模块有关的数据库表。

3、启用这个模块。这次，在模块启用时，Drupal会创建相关的数据库表。

    当Drupal创建了用来存储数据的block_morelink表以后，现在让我们添加与数据处理相关的代码。首先，我们需要在提交处理函数中添加一些逻辑代码，这样在用户修改了区块配置信息后，它可以用来处理与更多链接相关的数据。我们的表单提交函数如下所示：

function block_morelink_block_admin_configure_submit($form, &$form_state){

  db_delete('block_morelink')

    ->condition('module', $form_state['values']['module'])

    ->condition('delta', $form_state['values']['delta'])

    ->execute();

  if(!empty($form_state['values']['morelink_url'])){

  $query = db_insert('block_morelink')->fields(array('url', 'title', 'module', 'delta'));

 $query->values(array(

    'url' => $form_state['values']['morelink_url'],

    'title' => $form_state['values']['morelink_title'],

    'module' => $form_state['values']['module'],

    'delta' => $form_state['values']['delta'],

  ));

  $query->execute();

  }

}

由于我们在一个区块上只允许有一个更多链接，所以我们可以先删除以前的信息，然后把最新的信息插入到数据库中。对于我们与数据库之间的交互，首先需要注意的是，我们不需要考虑数据库连接，这是因为Drupal在它的引导指令中已经完成了这一工作。其次，对于上述代码，我们目前只需要了解它做了哪些操作就可以了：首先是删除与该区块相关的更多链接信息，接着做了一个判断，如果输入的更多链接路径不为空，此时我们将更多链接有关信息插入到block_morelink表中。这里面我们使用了db_delete、db_insert两个数据库操作函数，分别用来负责删除与插入操作。

   最后，我们需要修改block_morelink_form_block_admin_configure_alter中代码，这样，如果已经存在了一个更多链接，那么将把它从数据库中读取出来，并用来将其作为默认值传递给我们的表单元素。我们将原有的代码：

  $default_morelink_url = '';

  $default_morelink_title = '';

   替换为

  $result = db_query("SELECT url, title FROM {block_morelink} WHERE module = :module AND delta = :delta", array(

    ':module' => $form['module']['#value'],

    ':delta' => $form['delta']['#value'],

  ))->fetch();

  $default_morelink_url = empty($result)?'':$result->url;

  $default_morelink_title = empty($result)?'':$result->title;

    这里我们使用了db_query函数从数据库中取出更多链接的url、title，并将其设置为现有表单元素的默认值。对于db_query中的sql，这里需要注意两点：首先，在我们用到一个数据库表时，我们需要把它放到花括号{}里；这样可以方便的实现在数据库表名的前面添加前缀（关于表名前缀的更多信息，可参看文件sites/default/settings.php中的注释）。其次，我们在查询语句中使用了占位符“:module”和“:delta”，并为其提供了相应的变量，这样Drupal内置的安全机制就可以帮助我们阻止SQL注入。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

  对于我们的这个模块来说，现在已经到了万事俱备只欠东风的阶段了。我们已经准备好了数据，现在我们需要在区块中将其显示出来。对于区块，我们首先想到的是区块的模板文件，下面是Drupal核心中自带的区块模板文件：

<div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>

  <?php print render($title_prefix); ?>

<?php if ($block->subject): ?>

  <h2<?php print $title_attributes; ?>><?php print $block->subject ?></h2>

<?php endif;?>

  <?php print render($title_suffix); ?>

  <div class="content"<?php print $content_attributes; ?>>

    <?php print $content ?>

  </div>

</div>

    在这里面，html代码片段中间，嵌套了一些PHP变量，这些变量是在哪里定义的呢？Drupal中模板中的变量通常都是定义在预处理函数中的。对于block.tpl.php,其变量来源于template_preprocess、template_preprocess_block、template_process。其中template_preprocess_block是专门针对区块的预处理函数，其代码如下：

function template_preprocess_block(&$variables) {

  $block_counter = &drupal_static(__FUNCTION__, array());

  $variables['block'] = $variables['elements']['#block'];

  // All blocks get an independent counter for each region.

  if (!isset($block_counter[$variables['block']->region])) {

    $block_counter[$variables['block']->region] = 1;

  }

  // Same with zebra striping.

  $variables['block_zebra'] = ($block_counter[$variables['block']->region] % 2) ? 'odd' : 'even';

  $variables['block_id'] = $block_counter[$variables['block']->region]++;

  // Create the $content variable that templates expect.

  $variables['content'] = $variables['elements']['#children'];

  $variables['classes_array'][] = drupal_html_class('block-' . $variables['block']->module);

  $variables['theme_hook_suggestions'][] = 'block__' . $variables['block']->region;

  $variables['theme_hook_suggestions'][] = 'block__' . $variables['block']->module;

  $variables['theme_hook_suggestions'][] = 'block__' . $variables['block']->module . '__' . $variables['block']->delta;

  // Create a valid HTML ID and make sure it is unique.

  $variables['block_html_id'] = drupal_html_id('block-' . $variables['block']->module . '-' . $variables['block']->delta);

}

    在这个函数中定义了变量block、block_zebra、block_id、content、classes_array、block_html_id，同时还定义了区块的模板建议theme_hook_suggestions。但是这里面并没有为我们定义“更多链接”。可以在我们的模块中实现区块的预处理函数，为block变量追加一个morelink属性：

/**

 * 为block变量添加morelink属性

 * @see block.tpl.php

 */

function block_morelink_preprocess_block(&$variables) {

  $result = db_query("SELECT url, title FROM {block_morelink} WHERE module = :module AND delta = :delta", array(

    ':module' => $variables['block']->module,

    ':delta' => $variables['block']->delta,

  ))->fetch();

  $morelink_url = empty($result)?'':$result->url;

  $morelink_title = empty($result)?'':$result->title;

  $variables['block']->morelink = '<span class="block-more-link">' . l(t('More'), $morelink_url, array('attributes' => array('title' => $morelink_title))). '</span>';

}

    在这段代码中，我们首先取出来了“更多链接”的url，title。然后使用l()函数构建了一个更多链接。将block.tpl.php模板文件复制到了themes\bartik\templates目录下面，并编辑里面的代码，以输出更多链接：

<div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>

  <?php print render($title_prefix); ?>

<?php if ($block->subject): ?>

  <h2<?php print $title_attributes; ?>><?php print $block->subject ?></h2>

<?php endif;?>

  <?php print render($title_suffix); ?>

  <div class="content"<?php print $content_attributes; ?>>

    <?php print $content ?>

  </div>

<?php if ($block->morelink): ?>

    <?php print $block->morelink ?>

  <?php endif;?>

</div>

    这样，我们配置一下搜索表单区块，输入一个测试用的更多链接url、title。保存区块，回到区块的显示页面，我们就会看到一个更多链接。

                           图2-3搜索表单多了一个更多链接

    模块写到这里，功能基本上就完成了，如果是一个实际的项目，现在就可以将其应用于在线站点了。但是作为模块开发中的一个练习来讲，我们还需要进一步的来完善这个模块，使其具有较强的可配置性和可定制性。

  作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

   在我们的预处理函数中，在为morelink属性赋值时，我们直接使用了 l() 函数并附加了一些html标签，我们把html标签写死在了里面，如果别人使用我们的代码，他们想修改这一输出时，只有通过修改module文件中的对应代码才能实现。我们可以采用Drupal的主题函数的方式，来改进我们的代码：

/**

 * Implements hook_theme().

 *

 */

function block_morelink_theme(){

  return array(

    'block_morelink_link' => array(

       'variables' => array('url' => NULL,'title' => NULL,)

    ),

  );

}

/**

 * Returns HTML for a "more" link, like those used in blocks.

 *

 * @param $variables

 *   An associative array containing:

 *   - url: The url of the main page.

 *   - title: A descriptive verb for the link, like 'Read more'.

 */

function theme_block_morelink_link($variables) {

$output = "";

if(!empty($variables['url'])){

$morelink_label = t('More');

   $output .= '<span class="block-more-link">' . l($morelink_label, $variables['url'], array('attributes' => array('title' => $variables['title']))). '</span>';

}

return $output;

}

    同时修改预处理函数中的代码，将

$variables['block']->morelink = '<span class="block-more-link">' . l(t('More'), $morelink_url, array('attributes' => array('title' => $morelink_title))). '</span>';

    替换为：

$variables['block']->morelink =  theme('block_morelink_link', array('url' => $morelink_url, 'title' => $morelink_title))

    在这里面，我们将原来的逻辑放在了theme_block_morelink_link函数中了，注意对于这个主题函数，这里需要注意以下两点：首先、我们没有直接显性的调用theme_block_morelink_link，而是通过theme()函数调用，这样就利用了Drupal的主题覆写机制，其他Drupal开发者就可以在主题层覆写我们的主题函数了。其次，所有的主题函数，都需要在hook_theme中注册一下，只有这样才能被Drupal识别出来，hook_theme中返回的是一个数组，一个这样的钩子函数中可以注册多个主题函数。

    现在编辑bartik的template文件，我们在这个文件的最下面追加以下函数：

function bartik_block_morelink_link($variables) {

$output = "";

if(!empty($variables['url'])){

$morelink_label = t('More');

   $output .= '<div class="block-more-link">' . l($morelink_label, $variables['url'], array('attributes' => array('title' => $variables['title']))). '</div>';

}

return $output;

}

    这里我们没有直接修改module文件中的theme_block_morelink_link，就实现了对这个主题函数的覆写，将span标签替换为了div。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

我们在前面的代码中，morelink的标签t(‘More’)是写死在里面的，通过翻译机制我们可以将其翻译成任意的中文。但是如果这一文本，能够配置的话，那么这个模块就会更通用一点。如果你觉得现在已经足够好的话，那么也无需改进，我们这里仅仅是作为一个例子，让大家接触更多的钩子和API函数。

/**

 * Implements hook_menu().

 */

function block_morelink_menu() {

 // Block settings.

  $items['admin/config/block'] = array(

    'title' => 'Block',

    'description' => 'Block configuration.',

    'position' => 'left',

    'weight' => -10,

    'page callback' => 'system_admin_menu_block_page',

    'access arguments' => array('access administration pages'),

    'file' => 'system.admin.inc',

    'file path' => drupal_get_path('module', 'system'),

  );

  $items['admin/config/block/morelink'] = array(

    'title' => 'More link',

    'description' => 'the more link lable of block.',

    'page callback' => 'drupal_get_form',

    'page arguments' => array('block_morelink_label_settings'),

    'access arguments' => array('administer site configuration'),

    'weight' => -10,

   // 'file' => 'block_morelink.admin.inc',

  );

   return $items;

}

    这里我们实现了hook_menu(),它返回一个包含菜单项的数组。这里面每一项都以路径为键，在这里就是admin/config/block和admin/config/block/morelink。菜单项的值是一个数组，里面包含的键和值，描述了Drupal在处理该路径下的回调函数时可以做些什么。有关菜单方面的更多详细，可参看菜单系统一章。

Drupal的配置页面有多个类别，比如内容、用户、系统，都出现在主配置页面上。我们的配置是关于区块的，并没有一个类别特别适合我们。所以在这里，我们创建一个名为“Block”的新类别。

                 图2-4 显示在主配置页面的“Block”的新类别

在第二个菜单项中，我们将我们的配置页面放在“Block”类别的下面。这段代码说，“当用户访问页http://example.com/admin/config/block/morelink 时，调用函数drupal_get_form, 并向它传递一个表单ID block_morelink_label_settings作为参数。只有具有管理站点配置权限的用户才有权查看这个菜单。”当需要显示表单时，Drupal就会让我们提供一个表单定义。当有人访问这个路径时，Drupal就会将其映射到表单定义函数上。

function block_morelink_label_settings(){

  $form['block_morelink_label'] = array(

    '#type' => 'textfield',

    '#title' => t('More Link lable'),

    '#maxlength' => 40,

    '#description' => t('The More Link lable of the block as shown to the user.') ,

    '#default_value' =>  variable_get('block_morelink_label', t('More')),

    '#weight' => -17,

  );

  return system_settings_form($form, TRUE);

}

    注意这个表单定义函数，我们现在将其放在了module文件中，我们也可以创建一个block_morelink.admin.inc文件，然后将这个函数放在该文件中。此时需要取消“'file' => 'block_morelink.admin.inc',”前面的注释符号。Module文件中，通常只放置钩子函数和API函数，其它逻辑处理，通常都放在inc文件中。对于每个页面请求，Drupal通常都会加载所有的module文件，把相关文件放在inc文件中，有利于降低module文件的大小，可以实现缓加载，从而提升性能。但是我们的这个函数，代码量非常少，新增一个inc文件，也是有性能成本的。此时所带来的性能提升，可能还抵消不了新引入的性能成本。

在这个表单函数中，我们添加了一个文本输入框，允许用户输入更多链接的标签。在这里，我们自己没有管理表单的处理流程，而是使用了函数system_settings_form()来让系统模块为表单添加一些按钮，并让它来管理表单的验证和提交。图2-5给出了的当前表单的样子。

            图2-5  block_morelink的配置页面 

variable_get与variable_set 

    在前面的例子中，修改配置并点击“保存配置”按钮，就可以正常工作。下面部分将描述如何实现这一点。Drupal在数据库中有一个variable表，用来存储“名-值”对。使用variable_set（$key,$value）来存储“名-值”对，使用variable_get($key,$default)来取回“名-值”对。在前面的代码中，

  variable_get('block_morelink_label', t('More'))，

用来取回名为block_morelink_label的变量的值，如果这个值为空，则使用默认值t('More')。

    可能有读者会问，这个变量是怎么保存到数据库中的？由于我们调用了system_settings_form，我们的表单提交时，会调用system_settings_form_submit函数，在这个函数中，有以下代码：

foreach ($form_state['values'] as $key => $value) {

    if ($op == t('Reset to defaults')) {

      variable_del($key);

    }

    else {

      if (is_array($value) && isset($form_state['values']['array_filter'])) {

        $value = array_keys(array_filter($value));

      }

      variable_set($key, $value);

    }

  }

    它会按照表单元素的名字，来保存变量的值。所以我们要保证，表单元素的名称和variable_get里面的名称保持一致。在variable表中存储和取回设置时，为了避免命名空间的冲突，前面应该以模块名字开头。表单字段和变量的键应使用同一名字。

    现在，我们可以把theme_block_morelink_link($variables)函数中的相应代码替换掉了，将

$morelink_label = t('More');

    替换为

$morelink_label = variable_get('block_morelink_label', 'more');

    最后，由于我们在模块中，新增了一个变量，除了我们需要维护这个变量的读取与存储以外，我们还需要在这个模块被卸载时，能够删除它所定义的变量。在install文件中增加以下代码：

function block_morelink_uninstall(){

  variable_del('block_morelink_label');

}

    这里我们实现了hook_uninstall钩子，在这个钩子中，在这个模块被卸载时，使用variable_del函数删除变量block_morelink_label。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

尽管贡献自己的代码在中国这样的环境中，并不是很流行，但是环境还是在逐步的改善，通过向Drupal社区贡献自己的模块，如果你的模块被其它用户使用的话，也是可以为你带来很多潜在的机会的。开发好了block_morelink模块以后，我们可以在drupal.org上创建一个项目，然后将这个模块通过GIT上传上去，这样我们就将这个模块分享出去了。项目地址：http://drupal.org/project/block_morelink/。注意drupal.org上的模块，需要遵守GPL协议。

               图2-6  drupal.org上该模块项目页面

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

总结

    读完本章以后，我们应该掌握以下几点：

从头创建一个Drupal模块。

使用Drupal的表单API来创建简单的表单。

使用hook_form_FORM_ID_alter来修改其它表单。

了解Drupal的主题覆写机制

了解Drupal中的预处理函数

使用hook_schema创建数据库表

使用hook_menu建立简单的回调映射。

使用variable_get与variable_set来读取和存储配置信息。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

有时候，我们可能希望能够向回调函数提供更多的信息。首先，路径中的其它部分能够自动的作为参数传递过来。让我们修改一下我们的回调函数，增加两个参数：

/**

 * 菜单项menu_abc/sub的回调函数.

 */

function menu_abc_sub_callback_page($arg1 = '', $arg2 = ''){

  $render_array = array();

  $render_array['#markup'] = t('菜单ABC子页面内容 @arg1 @arg2', array('@arg1' =>

    $arg1, '@arg2' => $arg2));   

  return $render_array;

}

现在，如果我们访问http://localhost/thinkindrupal/menu_abc/sub/A/B/C，我们将得到如图3-11所示的输出。

图 3-11.路径的其余部分传递给了回调函数。

我们在这里需要注意，URL中的其余部分是如何作为参数传递给我们的回调函数的，注意A作为第一参数，B作为第二个参数传递了过来，而C则没有传递过来。

还可以在菜单钩子中定义页面回调的参数，只需要使用'page arguments'（页面参数）键即可。定义页面参数有时非常有用，这样我们就可以定义一个回调函数，供不同的菜单项调用，而菜单项则可以使用页面参数来传递上下文。让我们在我们的菜单项中定义一下页面参数：

  $items['menu_abc/sub'] = array(

    'title' => '菜单ABC子项',

    'description' => '菜单ABC的子项.',

    'page callback' => 'menu_abc_sub_callback_page',

'page arguments' => array('B', 'C'),

'file' => 'menu_abc.pages.inc',

    'access callback' => TRUE,

'weight' => 10,

'menu_name' => 'main-menu',

  );

我们在菜单钩子中定义的回调参数，将会首先传递给回调函数（也就是说，在传递给回调函数的参数列表中，它放在最前面），其次才是从路径中获取的参数。来自URL的参数仍然可用。让我们做一下测试，仍然访问http://localhost/thinkindrupal/menu_abc/sub/A/B/C，我们将看到如图3-12所示的结果（如果你没有得到这一结果，那你清空一下缓存）。

图 3-12.向回调函数中传递和显示参数

    此时，我们看到起作用的是菜单钩子中定义的回调参数，通过URL传递过来的参数则没有起任何作用。原因是我们这里只有两个参数，如果再添加两个参数的话：

/**

 * 菜单项menu_abc/sub的回调函数.

 */

function menu_abc_sub_callback_page($arg1 = '', $arg2 = '', $arg3 = '', $arg4 = ''){

  $render_array = array();

  $render_array['#markup'] = t('菜单ABC子页面内容 @arg1 @arg2 @arg3 @arg4',  array('@arg1' => $arg1, '@arg2' => $arg2, '@arg3' => $arg3, '@arg4' => $arg4));

  return $render_array;

}

    此时，我们再次访问页面menu_abc/sub/A/B/C，注意页面内容的变化：

     图 3-13.页面参数和URL参数

在页面回调参数的数组中，键被忽略了，只有值才有意义，所以你不能使用键来对应回调函数中的参数；在这里，是按照顺序走。回调参数通常是变量，并常用在动态菜单项中。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

有时候，Drupal的术语是异常晦涩难懂的，同样的名字，在Drupal中有着不同的含义，拿标签tabs来说，在Drupal中，我们把它叫做本地任务，对应的菜单类型为MENU_LOCAL_TASK或者MENU_DEFAULT_LOCAL_TASK。本地任务的标题通常是一个简短的动词，比如“添加”或者“列出”。它通常作用在一些对象上，比如节点,或者用户。我们可以把一个本地任务理解为一个关于菜单项的语义声明，通常显示为一个标签（tab）----这和<strong>标签类似，后者也是一个语义声明，通常用来显示加粗的文本。

为了显示标签，本地任务必须有一个父菜单项。一个常用的做法是将一个回调指定到一个根路径上，比如my，然后将本地任务指定到扩展了该路径的子路径上，比如my/orders、my/comments、my/favorites等等。Drupal内置的主题仅支持两级本地任务。（底层系统可以支持多级的本地任务，但是为了显示更多的层级，你需要让你的主题为此提供支持。）

本地任务的显示顺序是由菜单项标题的字母顺序决定的。如果这种顺序不是你想要的，那么你可以为你的菜单项添加一个weight键，然后它们将按照重量进行排序。

下面的例子中，将会生成了四个主标签。这是一个实际模块代码改造而来的实例，用来解决Drupal用户个人主页的调整。我们将模块名字命名为my，然后分别创建3个文件，my.info、my.module、my.pages.inc,之后向my.info文件中添加以下内容： 

name = 用户主页

description = 使用tabs作为用户主页导航

core = 7.x

接着，向my.module文件中添加以下代码：

<?php

/**

 * @file

 * 演示Drupal中菜单API本地任务的基本用法,

 */

/**

 * 实现 hook_menu().

 */

function my_menu() {

  $items['my'] = array(

    'title' => '我的主页',

    'page callback' => 'my_home_page',

    'file' => 'my.pages.inc',

    'access callback' => 'my_access_callback',

  );

$items['my/home'] = array(

    'title' => '我的主页',

    'page callback' => 'my_home_page',

    'file' => 'my.pages.inc',

    'access callback' => 'my_access_callback',

    'type' => MENU_DEFAULT_LOCAL_TASK,

    'weight' => 1,  

  );

$items['my/orders'] = array(

    'title' => '我的订单',

    'page callback' => 'my_orders_page',

    'file' => 'my.pages.inc',

    'access callback' => 'my_access_callback',

    'type' => MENU_LOCAL_TASK,

    'weight' => 2,

  );

$items['my/comments'] = array(

    'title' => '我的评论',

    'page callback' => 'my_comments_page',

    'file' => 'my.pages.inc',

    'access callback' => 'my_access_callback',

    'type' => MENU_LOCAL_TASK,

    'weight' => 3,  

  );

$items['my/favorites'] = array(

    'title' => '我的收藏',

    'page callback' => 'my_favorites_page',

    'file' => 'my.pages.inc',

    'access callback' => 'my_access_callback',

    'type' => MENU_LOCAL_TASK,

    'weight' => 4,

  );

  return $items;

}

/**

 * 页面回调.

 */

function my_access_callback(){

  global $user;

  $flag = FALSE;

  //只有注册用户才能访问自己的主页

  if($user->uid>0){

    $flag = TRUE;

  }

  return $flag;

}

    最后向my.pages.inc中添加对应的回调函数，注意回调函数中有注释，

<?php

/**

 * @file

 * my的各种回调函数,

 */

/**

 * 菜单项my的回调函数.

 */

function my_home_page(){

  global $user;

  $render_array = array();

  $render_array['#markup'] = t('我的主页页面内容');

  //逻辑代码，比如

  // $render_array['#markup'] .= views_embed_view('my_home', 'block', $user->uid);

  return $render_array;

}

/**

 * 菜单项my/orders的回调函数.

 */

function my_orders_page(){

  global $user;

  $render_array = array();

  $render_array['#markup'] = t('我的订单页面内容');

  //逻辑代码，比如

  // $render_array['#markup'] .= views_embed_view('my_orders', 'block', $user->uid);

  return $render_array;

}

/**

 * 菜单项my/comments的回调函数.

 */

function my_comments_page(){

  global $user;

  $render_array = array();

  $render_array['#markup'] = t('我的评论页面内容');

  //逻辑代码，比如

  // $render_array['#markup'] .= views_embed_view('my_comments', 'block', $user->uid);

  return $render_array;

}

/**

 * 菜单项my/favorites的回调函数.

 */

function my_favorites_page(){

  global $user;

  $render_array = array();

  $render_array['#markup'] = t('我的收藏页面内容');

  //逻辑代码，比如

  // $render_array['#markup'] .= views_embed_view('my_favorites', 'block', $user->uid);

  return $render_array;

}

    我们启用这个模块，访问http://localhost/thinkindrupal/my，看到如图4-14所示的效果。

                 图 3-14.采用了本地任务的个人主页

注意，页面的标题来自于父回调函数，而不是来自于默认的本地任务。如果你想使用一个不同的标题，那么可以使用drupal_set_title()来单独设置它。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

当Drupal重构menu_router表和更新menu_link表时（比如，当一个新模块被启用时），通过实现hook_menu_alter()，模块就可以修改任意的菜单项。例如，“我的帐户”菜单项通过调用user_page()，如果当前用户是登录用户，那么就显示用户的个人资料；如果是匿名用户，则显示登录表单。由于user_page ()函数位于modules/user/user.pages.inc中，所以该Drupal路径的菜单项中定义了file键。这样，通常情况下，当一个用户点击了用户菜单中的“我的帐户”链接，Drupal会加载文件modules/user/user.pages.inc并运行user_page ()函数。

    由于我们在my模块中，定义了自己的用户中心路径，我们希望当用户访问路径user的时候，能够重定向到我们新定义的个人主页。此时我可以通过hook_menu_alter钩子来修改Drupal系统自带的菜单项。在my.module文件中，添加以下内容：

/**

 * 实现 hook_menu_alter().

 */

function my_menu_alter(&$items){

  $items['user']['page callback'] = 'my_user_page';

  $items['user']['file'] = 'my.pages.inc';

  $items['user']['file path'] = drupal_get_path('module', 'my');

}

    向my.pages.inc中添加对应的回调函数：

/**

 * 菜单项user的回调函数.

 */

function my_user_page(){

  global $user;

  if($user->uid > 0){

    drupal_goto('my');

  }else{

    //drupal_goto('user/login');

    return drupal_get_form('user_login');

  }

}

在我们的hook_menu_alter()钩子函数运行以前，user路径的菜单项应该是这样的：

array(

    'title' => 'User account',

    'title callback' => 'user_menu_title',

    'page callback' => 'user_page',

    'access callback' => TRUE,

    'file' => 'user.pages.inc',

    'weight' => -10,

    'menu_name' => 'user-menu',

  );

当我们修改了它以后，就变成了这样：

array(

    'title' => 'User account',

    'title callback' => 'user_menu_title',

    'page callback' => 'my_user_page',

    'access callback' => TRUE,

    'file' => 'my.pages.inc',

    'file path' => drupal_get_path('module', 'my'),

    'weight' => -10,

    'menu_name' => 'user-menu',

  );

   清除缓存，当我们再次访问“我的帐户”链接时，系统就会重定向到我们新定义的页面。

    注意这里面，由于我们将my_user_page定义在了my.pages.inc中，所以此时我们还需要明确的定义$items['user']['file path']，否则系统就会默认的在modules/user目录下查找这个文件，并显示无法打开相应文件的错误信息。

   图 3-15.注释掉 'file path'的定义信息，就会报错。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

如果我们前面的修改，还不能令客户满意，而此时又需要进一步的隐藏系统自带的用户菜单。那么有多种方法，我们这里介绍通过实现hook_menu_link_alter()钩子函数，在Drupal将一个菜单项保存到menu_link表时，修改对应链接。下面是如何将“我的帐户”、“登出”菜单项隐藏的。

/**

 * 实现 hook_menu_link_alter().

 */

function my_menu_link_alter(&$item){

  if($item['link_path'] == 'user'){

    $item['hidden'] = 1;

}

if($item['link_path'] == 'user/logout'){

    $item['hidden'] = 1;

}

}

这个钩子可以用来修改一个链接的多个属性，比如标题、重量、是否隐藏。如果你需要修改一个菜单项的其它属性的话，比如访问回调，那么需要使用hook_menu_alter()。

       图 3-16.用户菜单的链接已被禁用

    此时，在用户菜单的管理界面，我们选择启用，并保存设置，我们发现两个菜单项仍然是禁用的，也就是说hook_menu_link_alter()中对菜单项所做的修改，是无法在用户界面中再进行覆写的。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

到目前为止,我们在菜单项中所用的都是普通的Drupal路径名字,比如menu_abc 、my、my/orders。但是Drupal还经常使用这样的路径,比如user/1或node/1/edit,在这些路径中,有一部分是动态的。现在,让我们来看看动态路径是如何工作的。

    我们为此单独创建一个模块menu_wildcard，首先创建menu_wildcard.info, menu_wildcard.module, menu_wildcard.pages.inc文件。然后向menu_wildcard.info中添加以下内容：

name = 菜单通配符

description = 用来学习菜单通配符的实例模块

core = 7.x

    接着向menu_wildcard.module文件添加以下代码：

<?php

/**

 * @file

 * 演示Drupal中菜单通配符的用法,

 */

/**

 * 实现 hook_menu().

 */

function menu_wildcard_menu() {

  $items['wildcard/%'] = array(

    'title' => '简单的通配符',

    'description' => '一个简单的包含通配符的菜单项.',

    'page callback' => 'menu_wildcard_callback_page',

'page arguments' => array(1),

'file' => 'menu_wildcard.pages.inc',

    'access callback' => TRUE,

  );

  return $items;

}

    最后向menu_wildcard.pages.inc文件中添加对应的回调函数：

<?php

/**

 * @file

 * menu_wildcard的各种回调函数,

 */

/**

 * 菜单项wildcard/%的回调函数.

 */

function menu_wildcard_callback_page($arg1 = '', $arg2 = '', $arg3 = '', $arg4 = ''){

  $render_array = array();

  $render_array['#markup'] = t('菜单通配符示例页面内容');

  $render_array['#markup'] .=  '<div>'.t('参数1：@arg1', array('@arg1' => $arg1)).'</div>';

  $render_array['#markup'] .=  '<div>'.t('参数2：@arg2', array('@arg2' => $arg2)).'</div>';

  $render_array['#markup'] .=  '<div>'.t('参数3：@arg3', array('@arg3' => $arg3)).'</div>';

  $render_array['#markup'] .=  '<div>'.t('参数4：@arg4', array('@arg4' => $arg4)).'</div>';

  return $render_array;

}

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

%字符在Drupal菜单项中是一个特殊的字符。它意味着“从这到下一个/字符之间的字符串”。上面是一个使用了通配符的菜单项。这个菜单项适用的Drupal路径可以有wildcard /a, wildcard/a/b, wildcard/88。但是它对路径wildcard不起作用；对于后者，因为它只包含了一个部分，而wildcard /%只匹配至少具有两部分的字符串，所以你需要为其单独创建一个菜单项。注意，尽管%通常是用来指定一个数字的（比如，user/%/edit用于user/1/edit），但是它能匹配该位置上的任何文本。

注意 在路径中带有通配符的菜单项，即便是将菜单项的类型设置为MENU_NORMAL_ITEM，它也不会显示在导航菜单中。原因很明显：由于路径中包含了一个通配符，所以Drupal不知道如何为该路径构建URL。这是一般情况下的规律，也有例外的情况，更多详细，可参看本章后面的“使用to_arg()函数为通配符构建路径”。

    我们访问路径wildcard/123，就会得到这样的结果：

                图 3-17.带有通配符的菜单项

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

我们新增一个菜单项：

function menu_wildcard_menu() {

  $items['wildcard/%'] = array(

    'title' => '简单的通配符',

    'description' => '一个简单的包含通配符的菜单项.',

    'page callback' => 'menu_wildcard_callback_page',

'page arguments' => array(1),

'file' => 'menu_wildcard.pages.inc',

    'access callback' => TRUE,

  );

  $items['wildcard/%/b'] = array(

    'title' => '普通的通配符',

    'description' => '一个普通的包含通配符的菜单项.',

    'page callback' => 'menu_wildcard_callback_page',

'page arguments' => array(1),

'file' => 'menu_wildcard.pages.inc',

    'access callback' => TRUE,

  );

  return $items;

}

    清空缓存后，让我们再次访问路径wildcard/123/b/c/d，得到如图3-19所示的结果。

图 3-19.通过URL只传递了两个参数c,d

第一个参数，123，是通过页面回调传递过来的。array(1)的意思是，“不管路径中的部分1是什么，请将它传递过来”。我们是从0开始算起的，所以部分0就是'wildcard '，部分1就是通配符所匹配的任何东西，部分2就是'b'，依次类推。此时，b是Drupal路径中的一部分了，不再通过URL传递。后面的c，d，也被传递了过来，它的传递原理我们在前面已经学过了，那就是Drupal路径后面的一部分将会作为参数传递给回调函数,注意图3-18和图3-19之间的区别。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

 向我们的菜单钩子中添加一个新的菜单项：

  $items['placeholder/%menu_wildcard_arg_optional'] = array(

    'title' => '占位符示例',

    'description' => '一个通配符用作占位符的菜单项.',

    'page callback' => 'menu_wildcard_callback_page',

'page arguments' => array(1),

'file' => 'menu_wildcard.pages.inc',

    'access callback' => TRUE,

  );

    并在module文件中添加一个新的函数：

function menu_wildcard_arg_optional_load($id){

  $mapped_value = "";

  $mappings = array(

  'a' => "美国",

'b' => "英国",

'c' => "中国",

);

  if (isset($mappings[$id])) {

    $mapped_value = $mappings[$id];

  }

  if(empty($mapped_value)){

$mapped_value = t('当前ID @id 没有对应的值',array('@id' => $id));

  }

  return $mapped_value;

}

     清空缓存，让我们访问路径placeholder/a/b/c/d,得到图3-20所示的结果。

          图 3-20.页面参数被_load()函数替换了

    参数a被替换成了“美国”，神奇吧！路经placeholder/%menu_wildcard_arg_optional是怎么一回事呢？我们在这里详细的解释一下：

    1.使用/字符将路径切分成各个部分。

    2.在第2部分中，匹配从%到下一个可能的/字符之间的字符串。在这里，该字符串就是menu_wildcard_arg_optional。

    3. 向该字符串上追加_load，来生成一个函数的名字。在这里，该函数的名字就是menu_wildcard_arg_optional_load。

    4. 调用该函数，并将Drupal路径中通配符的值作为参数传递给它。所以，如果Drupal路径为placeholder/a/b/c/d，那么通配符匹配的第2部分就是a，那么调用的就是menu_wildcard_arg_optional_load ('a')。

    5. 使用这个调用所返回的结果来替换通配符。这里的页面参数为array(1)，在页面回调被调用时，我们没有传递Drupal路径中的部分1（a），而是传递了menu_wildcard_arg_optional_load ('a')返回的结果，也就是“美国”。我们可以把它看作，Drupal路径中的一部分被它对应的_load()函数替换了。

    6. 注意，标题回调和访问控制回调也可以使用这种替换方式。

    在Drupal中，这种占位符形式的参数替换是非常常见的，比如最核心的node/%node，user/%user,就采用了这种方式。为了更好的理解这种替换，以node/%node/edit为例，我们可以把它看作是node/%/edit，外加了一个隐藏指令：为通配符匹配的内容运行node_load()。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

    菜单路径中的通配符，不影响将URL中的额外部分作为参数传递给页面回调，这是因为通配符只匹配到下一个/字符。继续使用我们的wildcard/%路径作为例子，对于URL  wildcard/123/b/c/d，通配符所匹配的字符串就是123，而对于路径中的其余部分（b/c/d），它们将分别作为参数传递给页面回调。

            图 3-18.通配符的值和URL中的参数部分都传递了过来

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

如果需要向加载函数传递额外的参数，那么可以使用load arguments键。下面是来自节点模块的例子：一个用来查看节点修订本的菜单项。在这里需要向加载函数，也就是node_load()，传递节点ID和修订本的ID。

  $items['node/%node/revisions/%/view'] = array(

    'title' => 'Revisions',

    'load arguments' => array(3),

    'page callback' => 'node_show',

    'page arguments' => array(1, TRUE),

    'access callback' => '_node_revision_access',

    'access arguments' => array(1),

  );

菜单项为load arguments键指定了array(3)。这意味着，除了节点ID通配符的值会自动传递给加载函数以外，还会向加载函数传递一个额外的参数。因为array(3)里面有个元素；我们在“使用通配符的值”一节中已经讲过，这意味着将会使用路径中的部分3。当路径node/12/revisions/29/view被访问时，由于这里定义了load arguments键，这就意味着将会调用node_load('12', '29')，而不是node_load('12')了。

当页面回调运行时，加载函数会将'12'替换为加载了的节点对象，所以页面回调将会是node_show($node, TRUE)。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

有两个特殊的加载参数。%map令牌将当前Drupal路径作为数组进行传递。在前面的例子中，如果%map作为一个加载参数传递过来的话，那么其值就为array('node', '12', 'revisions', '29', 'view')。如果加载函数的参数是通过引用传递的话，那么加载函数可以修改%map中对应的值。%index令牌在加载函数中指的是通配符的位置。对于前面的例子，由于通配符的位置为1，如表4-2所示，所以该令牌的值就为1。

    例如，在modules/user/user.module中，有这样的菜单项：

 $items['user/%user_category/edit/' . $category['name']] = array(

          'title callback' => 'check_plain',

          'title arguments' => array($category['title']),

          'page callback' => 'drupal_get_form',

          'page arguments' => array('user_profile_form', 1, 3),

          'access callback' => isset($category['access callback']) ? $category['access callback'] : 'user_edit_access',

          'access arguments' => isset($category['access arguments']) ? $category['access arguments'] : array(1),

          'type' => MENU_LOCAL_TASK,

          'weight' => $category['weight'],

          'load arguments' => array('%map', '%index'),

          'tab_parent' => 'user/%/edit',

          'file' => 'user.pages.inc',

        );

    它对应的加载函数就是user_category_load($uid, &$map, $index)。这个菜单项向加载函数传递了参数array('%map', '%index')。如果用户通过路径'user/32/edit/foo'来编辑类别为foo的帐户信息，此时将会调用user_category_load函数，它的第一个参数的值为32，第2个参数的值为('user', 32, 'edit', 'foo')，第3个参数的值为1（也就是通配符所在的索引位置，注意是从0算起的）。user_category_load就会根据这些信息，把foo类别下的对应信息提取出来。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

还记不记得前面我们曾经说过，对于包含通配符的Drupal路径，Drupal无法为其创建一个有效的链接，比如node/%（毕竟，Drupal怎么会知道如何替换%呢）？不过这一点并非完全正确。我们可以定义一个帮助函数，来为通配符参数提供一个默认值，这样，在Drupal构建链接时，就有路径可用了。向我们的模块的module文件中追加以下函数：

/**

 * to_arg()函数的实现

 */

function menu_wildcard_arg_optional_to_arg($arg){

  return (empty($arg) || $arg == '%') ? 'a' : $arg;

}

清除缓存，这样，链接“占位符示例”就会出现在导航区块中了。该链接的Drupal路径为placeholder/a。

    to_arg()函数，最初应用于“我的帐户”这一链接上，但在Drupal7的正式版本中，“我的帐户”对应路径已被修改为了user,不带任何通配符。而与uid相关的信息则是从global $user中提取出来的。随着此处弃用了to_arg()函数，Drupal核心中，好像再也找不到实际的例子了。而这种方式，在实际的站点开发中，很少被用到。

作者：老葛，北京亚艾元软件有限责任公司，http://www.yaiyuan.com

    "title":必须的。菜单项未翻译的标题。

    "title callback": 用来生成标题的函数。默认为t()。如果你只想输出原始的字符串，那么可以将这个键设置为FALSE。

    "title arguments":传递给标题回调函数的参数

    "description":菜单项未翻译的描述。

    "page callback": 当用户访问这个路径时，为了显示页面内容，所需要调用的回调函数。如果忽略这个键值，那么将会使用父菜单项的回调函数。

    "page arguments":传递给页面回调函数的参数。

    "delivery callback": 把页面回调函数返回的结果打包并传递给浏览器，所调用的函数。默认为drupal_deliver_html_page()，也可以从父菜单项继承过来。注意，即便是没有通过访问控制检查，Drupal也会调用这个函数，注意在自定义交付回调函数（delivery callback）时，要考虑这一点。

    "access callback":访问控制回调函数，如果用户具有访问这个菜单项的权限，那么返回TRUE，否则返回FALSE。这里可以使用布尔值来代替函数，当然也可以使用数字（会自动转换为布尔值）。默认为user_access()，或者是从父菜单项继承过来；只有MENU_DEFAULT_LOCAL_TASK类型的菜单项才可以从父菜单项中继承。为了使用user_access()，你需要指定需要检查的权限。

    "access arguments": 传递给访问控制回调函数的参数。如果访问控制回调函数是继承过来的，那么访问控制参数也可以继承过来，除非在子菜单项中覆写访问控制参数。

    "theme callback": 这个函数用来返回呈现该页面所用主题的机读名字。如果没有提供，它的值将会从父菜单项中继承过来。如果没有主题回调函数，或者该函数没有返回站点的当前主题，那么这个页面所用的主题将由hook_custom_theme()决定，或者采用默认主题。通常只在非常特别的情况下，使用这个键，那就是这些页面的功能与特定主题完全绑定在了一起，此时只有采用hook_menu_alter()才能覆写这些页面。如果想要实现通用的主题切换功能，应该使用hook_custom_theme()钩子函数。

    "theme arguments": 传递给主题回调函数的参数。

    "file":在调用页面回调函数前，所需要加载的文件；它允许将页面回调函数放在单独的文件中，该文件应该存放在相对于当前模块的目录，也可以使用"file path"键指定文件所在的目录。这个键只适用于页面回调函数。

    "file path": 页面回调函数所在文件的目录所在。默认为当前模块所在的路径。

    "load arguments": 一个参数数组，用在页面参数后面，传递给路径中的每个通配符对象加载器。

    "weight": 一个整数，用来决定菜单项的相对位置。越重的菜单项越靠后。默认为0。重量相同的菜单项按字母顺序排序。

    "menu_name": 默认为导航菜单，如果你不想把菜单项放到这里，那么可以设置一个自定义的菜单。

    "context": 定义标签可以出现在的上下文。默认情况下，所有标签只在页面上下文中显示为了本地任务。如果想把这些标签作为上下文链接显示在页面区域容器中，那么需要使用下面的上下文：

    •MENU_CONTEXT_PAGE:对于页面上下文，标签被显示为本地任务。

    •MENU_CONTEXT_INLINE:在页面上下文外面，标签被显示为上下文链接。

    上下文可以联合使用，如果想把标签既显示成为本地任务，也显示为上下文链接，那么可以这样定义：

<?php

      'context' => MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE,

 ?>

    "tab_parent":对于本地任务菜单项，本地任务的父菜单项的路径。比如'admin/people/create'的默认父菜单项为'admin/people'。

    "tab_root": 对于本地任务菜单项，最近的非标签菜单项的路径；默认与"tab_parent"相同。

    "position": 这个条目对应区块在系统管理页面的位置('left' 或者 'right')。

    "type": 菜单项的类型，可用值有MENU_NORMAL_ITEM、MENU_CALLBACK、MENU_SUGGESTED_ITEM、MENU_LOCAL_ACTION、MENU_LOCAL_TASK、MENU_DEFAULT_LOCAL_TASK。 如果忽略了"type"，那么会使用默认的MENU_NORMAL_ITEM。

    "options":在根据这个菜单项生成链接时，传递给l()函数的选项数组。