区块包含一个标题和一个描述，主要用于广告、代码片段和状态指示器，它不适用于主内容片段；因此，区块不是节点，它与节点有着不同的规则。节点可以具有多种功能：修订本控制，完善的访问权限，附带评论的能力，RSS种子和分类术语，等等；它们通常用于一个站点的主内容部分。

       区域是站点上用来放置区块的部分。区域的创建和显示是由主题（位于主题的.info文件中）负责的，而不是通过区块API来定义。没有指定区域的区块将不会显示出来。

       可以通过配置选项来控制谁可以访问区块，以及区块出现在站点的哪些页面。如果启用了节流阀模块，当访问量超过一定阀值时，一些不重要的区块，将被自动关闭。区块列表页面如图9-1所示。

       可以通过Drupal管理界面创建区块（称作自定义区块），也可以通过区块API用代码创建区块（称作模块区块）。当你创建区块时，该选用哪种方法呢？一次性的区块，比如一个与站点相关的一小段静态HTML，那么适用于自定义区块。如果区块本身具有动态性，与你编写的模块相关，或者里面大部分都是php代码，那么可以使用区块API通过模块来创建。由于代码存放在数据库中比写在模块中更难于维护，所以尽量不要在自定义区块中使用php代码，一个站点的编辑人员可能对此并不了解，他可能会偶然的不经意间将大量工作轻易的删掉。退一步讲，如果使用模块创建区块过于笨重，而又不得不使用php代码时，那么可以在区块中调用一个自定义函数，而将函数存放在别处。

 

图9-1，当启用了节流阀模块时，区块列表页面显示了节流阀选项

 

 

       尽管区块API很简单，并且只有单个钩子函数hook_block()，但是在这一框架下，你可以实现许多复杂的事情。区块可以显示你所想要的任何东西（这是因为，由于它们是用php实现的，所以在功能上没有限制）。尽管如此，它们通常扮演一个对站点主内容进行支撑的角色。比如，你可以为每一个用户角色创建一个自定义导航区块，或者你可以在区块中列出等待批准的评论。

 老葛的Drupal培训班 Think in Drupal

开发人员通常不需要担心区块的可见性，因为可以通过区块管理界面“管理➤站点构建➤区块”来处理大多数的情况。使用如图9-2所示的界面，你可以控制以下选项：

 

       特定用户可见性设置：管理员可以允许个人用户在他们的帐号设置中定制给定区块的可见性。用户可以通过单击他们的“我的帐号”链接来修改区块的可见性。

 

       特定角色可见性设置：管理员可以选择让区块仅对具有特定角色的用户可见。

 

       特定页面可见性设置：管理员可以选择让区块仅对特定页面或者特定范围内的页面可见或者隐藏，或者在你的php代码返回值为真的情况下可见。

 

图9-2管理界面中区块配置选项截图

我在前面提到，在Drupal的区块管理页面中，站点管理员可以选择将区块放置在哪个区域中。在同一页面，他们还可以对同一区域内的不同区块进行排序，如图9-1所示。区域是通过主题层的.info文件定义的，而不是通过区块API，而且不同的主题可以有不同的区域。关于创建区域的更多信息，参看第8章。

 

可以在模块中使用钩子hool_block()来定义区块，而且一个模块可以在单个钩子中实现多个区块。一旦区块定义好了以后，那么它将会出现在区块管理页面。另外，站点管理员可以通过后台管理界面来手工的创建自定义区块。在本节中，我们主要讨论如何通过代码创建区块。让我们看一下区块的数据库模式，如图9-3所示。

 

图9-3 区块的数据库模式

 

       每个区块的区块属性都存储在表blocks里面。通过区块配置界面为区块创建的其它数据，比如它们的内容和输入格式类型，都存放在表boxes里面。最后，表blocks_roles存放每个区块的基于角色的权限。下面的属性定义在表blocks的列中：

 

• bid：这是每个区块的唯一的标识ID。

 

module：这一字段存放的是定义区块的模块的名称。比如，用户登录区块是在用户模块中定义的，等等。对于管理员在“管理➤站点构建➤区块”中创建的自定义区块，它们将被认为是由区块模块创建的。

 

delta：由于一个模块可以在钩子hook_block()中定义多个区块，所以delta存放了每个区块的键，它们在钩子hook_block()范围内是唯一的，但对于整个站点的所有区块则不一定唯一。delta可以是整数，也可以是字符串。

 

theme：一个区块可以用于多个主题。因此，Drupal需要存放启用了该区块的主题的名称。启用了该区块的每个主题，在数据库中都有一行自己的记录。配置选项不能在主题之间共享。

 

status：它用来追踪区块是否被启用。1意味着启用，0意味着禁用。如果一个区块，没有为其指定一个区域，那么Drupal会将其状态设置为0.

 

• weight:区块的重量，用来决定区块在区域中的相对位置。

 

• region: 放置该区块的区域的名字，例如，页脚。

 

• custom: 这是这个区块的“特定用户可见性设置”的值（参看图9-2）。0意味着用户不能控制该区块的可见性；1意味着该区块默认是显示的，但是用户可以隐藏它；2意味着该区块默认是隐藏的，但是用户可以选择显示它。

 

throttle：当节流阀模块启用时，该字段用于追踪哪些区块可被节流。0意味着禁用节流，1意味着启用。节流阀模块能够自动的探测访问流量，当流量超过了阀值，它能临时的禁用一些耗费资源的区块（更多详细，可参看第22章）。

 

• visibility: 这个值用来表示如何判定区块的可见性。0意味着区块将显示在除所列页面以外的所有页面；1意味着区块只显示在所列页面；2意味着，Drupal将执行一段由管理员定义的PHP代码，以判定区块的可见性。

 

• pages: 该字段的内容依赖于visibility字段中的设置。如果visibility字段的值为0或1，那么该字段将包含一列Drupal路径。如果visibility字段的值为2，那么该字段将包含一段PHP代码，通过对其计算来判定是否需要显示区块。

 

• title:这是区块的自定义标题。如果这个字段为空，那么将使用区块的默认标题（由区块所在的模块提供）。如果这个字段包含的为<none>，那么该区块就没有标题。否则，该字段的文本将用作区块的标题。

 

• cache: 这个值用来判定Drupal是如何缓存该区块的。–1意味着区块不被缓存。1意味着为每个角色缓存区块，如果没有声明缓存设置，那么这是Drupal区块的默认设置。2意味着为每个用户缓存区块。4意味着为每个页面缓存区块。8意味着区块将被缓存，但是不管是什么角色，什么用户，什么页面，缓存的方式都是一样的。

 

在一个页面请求周期内，主题系统向区块系统请求返回每个区域内的一列区块。当为页面模板文件(通常为page.tpl.php)变量赋值时，完成这一步骤。对于每个区域（比如，页脚区域），为了聚集主题化的区块，Drupal执行以下类似的代码：

$variables['footer'] = theme('blocks', 'footer');

    你可能还记得第8章里面的theme(“block”)，它实际上就是调用方法theme_blocks()。下面是theme_blocks()的代码：

/**

 * Return a set of blocks available for the current user.

 *

 * @param $region

 * Which set of blocks to retrieve.

 * @return

 * A string containing the themed blocks for this region.

 */

function theme_blocks($region) {

    $output = '';

 

    if ($list = block_list($region)) {

        foreach ($list as $key => $block) {

            $output .= theme('block', $block);

        }

    }

 

    // Add any content assigned to this region through drupal_set_content() calls.

    $output .= drupal_get_content($region);

 

    return $output;

}

 

    在前面的代码中，我们对每个给定区域中的区块进行迭代，并为每个区块执行一个主题函数调用，一般最终会调用block.tpl.php文件。有关主题化的原理，以及如何覆写单个区块的外观，参看第8章。最后，我们为调用代码返回该区域内所有主题化的区块。

 

在用代码创建区块时，我们在区块钩子hook_block（）中处理所有的逻辑。通过这个钩子，你可以创建单个区块或者一组区块。任何模块都可以通过实现钩子hook_block（）来创建区块。让我们看一下函数签名：

function hook_block($op = 'list', $delta = 0, $edit = array())

 

参数列表

    区块钩子中使用的参数将在下面讨论。

 

$op

    这一参数用于定义区块所经过的阶段。通过传递参数$op来定义一个操作阶段，这一模型在Drupal框架中是很常用的---例如hook_nodeapi()和hook_user()中都用到了这一模型。$op的可能值如下：

 

list：返回一个数组，里面包含了该模块定义的所有区块。数组的键就是delta(在本模块定义的所有区块中，它是唯一的标识符)。每个数据元素的值，还是一个数组，里面提供了区块的重要数据。list的可能值和默认值，如下所示：

 

    info：这个值是必须的。一个可翻译的字符串（例如，使用t()封装），为站点管理员提供了一个合适的区块描述。

 

    cache: 这个区块如何被缓存？可能的值有LOCK_NO_CACHE (不缓存区块), BLOCK_CACHE_PER_ROLE (为每个角色缓存区块),    BLOCK_CACHE_PER_USER (为每个角色缓存区块----站点用户多了最好不要用这种方式!), BLOCK_CACHE_PER_PAGE (为每个页面缓存区块), 和BLOCK_CACHE_GLOBAL (缓存一次区块，所有的都一样)。

 

    status：区块默认应该被启用吗----True 还是 FALSE？默认为FALSE。

 

    region：可能为区块设置的默认区域。当然，管理员可以将区块移到一个不同的区域中。只有当状态值为TRUE时，区域的值才会有效；如果区块未被启用，那么区域将被设置为None。

 

    weight：它控制着区块在它的区域内的放置次序。重量越小，位置越靠前，水平方向是靠左，垂直方向是靠上。重量越大，越靠后。默认值为0.

 

    pages：定义区块所在的默认页面。默认是一个空字符串。pages的值包含了通过换行分隔的Drupal路径。*为通配符。例如，路径blog为日志首页，而blog/*则为个人日志页面。<front>代表首页。

 

    custom：TRUE意味着这是一个自定义区块，而FALSE则意味着它是通过模块实现的区块。

 

    title:默认区块标题。

 

    configure:返回一个数组，里面包含了用于特定区块设置的表单字段定义。它与区块配置页面的表单合并在了一起，从而使你能够扩展区块的配置方式。如果你实现了这个操作，那么你还需要实现save操作 (参看下一项)。

 

    save：在配置表单提交时被调用。当你的模块可以保存你在configure操作中收集的自定义区块配置信息时，使用该操作。你想保存的数据包含在参数$edit中。它不需要返回值。

 

    view：区块正被显示。返回一个包含了区块标题和内容的数组。

 

$delta

    这是要返回的区块ID。你可以为$delta使用一个整数或者一个字符串。注意当参数$op为list时，因为delta是在list操作中定义的，所以$delta此时将被忽略。

 

$edit

    当$op为save时，$edit包含了从区块配置表单提交过来的表单数据。

 

在这个例子中，你将创建两个区块，它们使得内容审核更易于管理。首先，你将创建一个区块用来列出等待批准的评论，然后你将创建一个区块用来列出未发布的节点。两个区块都为其中的每个待审核内容提供了链接，用来指向内容编辑表单页面。

       让我们创建一个名为approval.module的模块，它将包含我们的区块代码。在路径sites/all/modules/custom下面创建一个名为approval的文件夹（如果modules和custom不存在的话，你需要创建它们）。

       接下来，向文件夹中添加approval.info文件：

 

; $Id$

name = Approval

description = Blocks for facilitating pending content workflow.

package = Pro Drupal Development

core = 6.x

 

接着，再添加approval.module文件：

<?php

// $Id$

 

/**

 * @file

 * Implements various blocks to improve pending content workflow.

 */

 

    当你创建好这些文件后，在“管理➤站点构建 ➤模块”下面启用该模块。你还会用到approval.module，所以不要关闭文本编辑器。

       让我们添加区块钩子并实现list操作，这样，我们的区块就会出现在区块管理页面上的区块列表中（参看图9-4）。

/**

 * Implementation of hook_block().

 */

function approval_block($op = 'list', $delta = 0, $edit = array()) {

    switch ($op) {

        case 'list':

            $blocks[0]['info'] = t('Pending comments');

            $blocks[0]['cache'] = BLOCK_NO_CACHE;

            return $blocks;

    }

}

 

图9-4 在区块列表页面，你可以看到你创建的区块“Pending comments”了，它位于Disabled标题下面。它现在可被指定到一个区域中。

 

    注意数组的info键不是区块启用时所显示给用户的区块标题。而是一个仅仅出现在区块列表页面中的描述。你将在接下来的view操作中实现真正的区块标题。首先，你需要创建其它的配置选项，为了实现这一点，需要实现configue操作，如下面的代码所示。你创建了一个新的表单字段，当你点击区块列表页面中区块右边的配置链接时，即可看到这个字段，如图9-5所示。

 

function approval_block($op = 'list', $delta = 0, $edit = array()) {

    switch ($op) {

        case 'list':

            $blocks[0]['info'] = t('Pending comments');

            $blocks[0]['cache'] = BLOCK_NO_CACHE;

            return $blocks;

 

       case 'configure':

           $form['approval_block_num_posts'] = array(

              '#type' => 'textfield',

              '#title' => t('Number of pending comments to display'),

              '#default_value' => variable_get('approval_block_num_posts', 5),

           );

           return $form;

    }

}

 

图9-5 带有区块自定义字段的区块配置表单

当如图9-5所示的区块配置表单被提交后，它将触发下一个$op，这就是save。你将使用它来保存表单字段的值。

 

function approval_block($op = 'list', $delta = 0, $edit = array()) {

    switch ($op) {

        case 'list':

            $blocks[0]['info'] = t('Pending comments');

            $blocks[0]['cache'] = BLOCK_NO_CACHE;

            return $blocks;

 

        case 'configure':

            $form['approval_block_num_posts'] = array(

            '#type' => 'textfield',

            '#title' => t('Number of pending comments to display'),

            '#default_value' => variable_get('approval_block_num_posts', 5),

            );

            return $form;

 

       case 'save':

           variable_set('approval_block_num_posts',

              (int)$edit['approval_block_num_posts']);

           break;

    }

}

通过使用Drupal自带的变量系统的函数variable_set()，你将区块中显示的待定评论的数目保存了下来。注意这里使用了类型转换，将其转换为了整数，目的是对数据进行明智检查。最后添加view操作，当区块显示时，返回一个待定评论列表。

 

function approval_block($op = 'list', $delta = 0, $edit = array()) {

    switch ($op) {

        case 'list':

            $blocks[0]['info'] = t('Pending comments');

            return $blocks;

 

        case 'configure':

            $form['approval_block_num_posts'] = array(

                '#type' => 'textfield',

                '#title' => t('Number of pending comments to display'),

                '#default_value' => variable_get('approval_block_num_posts', 5),

            );

            return $form;

 

        case 'save':

            variable_set('approval_block_num_posts',

                (int)$edit['approval_block_num_posts']);

            break;

 

        case 'view':

            if (user_access('administer comments')) {

               // Retrieve the number of pending comments to display that

               // we saved earlier in the 'save' op, defaulting to 5.

               $num_posts = variable_get('approval_block_num_posts', 5);

 

               // Query the database for unpublished comments.

               $result = db_query_range('SELECT c.* FROM {comments} c WHERE

               c.status = %d ORDER BY c.timestamp', COMMENT_NOT_PUBLISHED, 0,

               $num_posts);

 

               // Preserve our current location so user can return after editing.

               $destination = drupal_get_destination();

               $items = array();

               while ($comment = db_fetch_object($result)) {

                   $items[] = l($comment->subject, 'node/'. $comment->nid,

                      array('fragment' => 'comment-'. $comment->cid)) .' '.

                      l(t('[edit]'), 'comment/edit/'. $comment->cid,

                      array('query' => $destination));

               }

 

               $block['subject'] = t('Pending comments');

               // We theme our array of links as an unordered list.

               $block['content'] = theme('item_list', $items);

            }

            return $block;

    }

}

这里，我们通过对数据库进行查询来获得待定的评论，将评论的标题显示为链接，同时为每一个评论追加一个编辑链接，如图9-6所示。

    注意，在前面的代码中，我们是如何使用方法drupal_get_destination()的。这个方法将记住在你提交表单以前你所在的页面，所以当你更新一个评论以后（或者发布，或者删除），它将自动重定向到你原来所在的页面。

    你还使用下面的代码设置了区块标题：

 

$block['subject'] = t('Pending comments');

 

图9-6 “待定评论”列表区块在它启用后的情况。它展示了两个待定评论。

 

    现在“待定评论”区块已经完成，让我们在approval_block()函数中定义另一个区块----它列出了所有未发布的节点，并提供了一个指向它们编辑页面的链接。

 

function approval_block($op = 'list', $delta = 0, $edit = array()) {

    switch ($op) {

        case 'list':

            $blocks[0]['info'] = t('Pending comments');

            $blocks[0]['cache'] = BLOCK_NO_CACHE;

           $blocks[1]['info'] = t('Unpublished nodes');

           $blocks[1]['cache'] = BLOCK_NO_CACHE;

            return $blocks;

    }

}

 

    注意这里是如何为每一个区块指定一个键的($blocks[0], $blocks[1], . . . $blocks[n])。区块模块将最终使用这些键作为$delta参数。这里我们将“待定评论”区块的$delta ID定义为0，“未发布节点”区块的$delta ID定义为1。在这里也可以使用“待定”和“未发布”作为键。根据程序员的判断来决定使用哪种键，而键不一定是数字形式，也可以是字符串。

下面是完整的函数，我们的新区块如图9-7所示：

 

function approval_block($op = 'list', $delta = 0, $edit = array()) {

    switch ($op) {

        case 'list':

            $blocks[0]['info'] = t('Pending comments');

            $blocks[0]['cache'] = BLOCK_NO_CACHE;

 

            $blocks[1]['info'] = t('Unpublished nodes');

            $blocks[1]['cache'] = BLOCK_NO_CACHE;

            return $blocks;

 

        case 'configure':

            // Only in block 0 (the Pending comments block) can one

            // set the number of comments to display.

            $form = array();

            if ($delta == 0) {

                $form['approval_block_num_posts'] = array(

                    '#type' => 'textfield',

                    '#title' => t('Number of pending comments to display'),

                    '#default_value' => variable_get('approval_block_num_posts', 5),

                );

            }

            return $form;

 

        case 'save':

            if ($delta == 0) {

                variable_set('approval_block_num_posts', (int)

                    $edit['approval_block_num_posts']);

            }

            break;

 

        case 'view':

            if ($delta == 0 && user_access('administer comments')) {

               // Retrieve the number of pending comments to display that

               // we saved earlier in the 'save' op, defaulting to 5.

                $num_posts = variable_get('approval_block_num_posts', 5);

               // Query the database for unpublished comments.

                $result = db_query_range('SELECT c.* FROM {comments} c WHERE c.status = %d ORDER BY c.timestamp', COMMENT_NOT_PUBLISHED, 0, $num_posts);

 

                $destination = drupal_get_destination();

                $items = array();

                while ($comment = db_fetch_object($result)) {

                    $items[] = l($comment->subject, 'node/'. $comment->nid,

                    array('fragment' => 'comment-'. $comment->cid)) .' '.

                    l(t('[edit]'), 'comment/edit/'. $comment->cid,

                    array('query' => $destination));

                }

 

                $block['subject'] = t('Pending Comments');

                // We theme our array of links as an unordered list.

                $block['content'] = theme('item_list', $items);

            }

            elseif ($delta == 1 && user_access('administer nodes')) {

               // Query the database for the 5 most recent unpublished nodes.

               // Unpublished nodes have their status column set to 0.

               $result = db_query_range('SELECT title, nid FROM {node} WHERE

               status = 0 ORDER BY changed DESC', 0, 5);

               $destination = drupal_get_destination();

               while ($node = db_fetch_object($result)) {

                   $items[] = l($node->title, 'node/'. $node->nid). ' '.

                      l(t('[edit]'), 'node/'. $node->nid .'/edit',

                      array('query' => $destination));

               }

 

               $block['subject'] = t('Unpublished nodes');

               // We theme our array of links as an unordered list.

               $block['content'] = theme('item_list', $items);

               }

            return $block;

    }

}

 

       由于你有多个区块，在view操作下，你使用了if…elseif构造体。在每一种情况下，你检查被查看区块的$delta以决定你是否应该运行该段代码。在脚本形式里，它看起来是这样的：

if ($delta == 0) {

// Do something to block 0

}

elseif ($delta == 1) {

// Do something to block 1

}

elseif ($delta == 2) {

// Do something to block 2

}

 

    在“未发布节点”区块启用后，区块的最终结果如图9-7所示。

图9-7，一个区块，列出了未发布节点

 

function userapproval_block($op = 'list', $delta = 0, $edit = array()) {

switch ($op) {

case 'list':

$blocks[0]['info'] = t('Pending users');

return $blocks;

case 'view':

if (user_access('administer users')) {

 $result = db_query_range('SELECT uid, name, created FROM {users}

 WHERE uid != 0 AND status = 0 ORDER BY created DESC', 0, 5);

 $destination = drupal_get_destination();

 // Defensive coding: we use $u instead of $user to avoid potential namespace

 // collision with global $user variable should this code be added to later.

 while ($u = db_fetch_object($result)) {

    $items[] = theme('username', $u). ' '.

    l('[edit]', 'user/'. $u->uid. '/edit', array(), $destination);

 }

 $block['subject'] = t('Pending users');

 $block['content'] = theme('item_list', $items);

}

return $block;

}

}

有时，你想在安装模块时，将一个区块自动显示出来。这非常直接，通过查询语句直接将区块的设置信息插入到blocks表中即可。查询放在钩子hook_install()中,该钩子位于模块的.install文件中。下面是一个例子，当Drupal被安装时，用户模块启用了用户登录区块（参看modules/system/system.install）：

 

db_query("INSERT INTO {blocks} (module, delta, theme, status, weight, region,

    pages, cache) VALUES ('%s', '%s', '%s', %d, %d, '%s', '%s', %d)",

    'user', '0', 'garland', 1, 0, 'left', '', -1);

 

    上面的数据库查询语句将区块插入到了blocks表中，并将它的状态设置为1，这样它就被启用了。这里将其指定给了left区域，也就是左边栏。

 

老葛的Drupal培训班 Think in Drupal

在区块管理界面，你可以在区块配置页面的“页面可见性设置”部分里面加入php代码片段。当一个页面被构建时，Drupal将运行php代码片段来决定区块是否显示。一些常用的代码片段例子如下所示；每段代码都应该返回TRUE或FALSE，来指示区块对于特定请求是否可见。

 

仅将区块显示给登录用户

    当$user->id不为0时，返回TRUE。

 

<?php

    global $user;

    return (bool) $user->uid;

?>

 

仅将区块显示给匿名用户

    当$user->id为0时，返回TRUE。

 

<?php

    global $user;

    return !(bool) $user->uid;

?>

 

在本章中，你学到了以下几点：

    drupal区块是什么以及它们与节点的区别

    drupal区块的可见性和位置设置是如何工作的

    如何定义一个或多个区块

    如何在默认情况下启用一个区块