2.1 区块与配置

我们已经了解了构建模块的几个必要条件,接下来看下 Drupal 8 中最常用的组件:区块和表单。

Drupal 8 中的块 API 变了,现在块既是插件(plugins)也是实体(entities)。

Drupal 8 中的块由两部分 API 组成:

  •  块插件 API :一个独立可重用的 API
  •  块实体 API :处理块的位置和可见性控制

这意味着现在块是可字段化的实体和正在使用新的插件系统(change record here)。

也意味着我们可以创建新的绑定,追加字段,使用不同方式查看它们。

现在一个区块可以同时显示在多个区域(regions)内,这在 Drupal 8 之前是不可以的。
实质上现在是可以创建同一个块的多个实例了。
你也可以通过 UI 把一个块同时放在不同的区域,不会发生冲突。

本课我们将使用 Examples 项目的 block_example 模块。

本课学习内容

  • 创建 examples/block_example 模块
  • 介绍 Drupal 8 中的注解
  • 探讨如何使用 Drupal GUI 添加区块
  • 学习 Form API
  • 探讨如何使用 Form API
  • 研究如何创建带有表单的区块和页面

Drupal 8 区块

不必使用 4 个钩子定义区块了(Drupal 7 中你必须这样做),插件系统支持以下内容:

  • 一个区块一个文件
  • 如果你想创建新区块,可以直接拷贝、修改之前区块文件,即得到新区块。
  • 以往修改区块需要处理位于不同位置的四个函数,且这些函数可能在两个文件里。
    现在区块内容只在一个文件内。
  • 所有逻辑都在那个文件
  • 你不需要去任何 info 文件声明你的类路径,因为它会被自动加载。
  • 区块很好地被封装在一个独立文件内

创建一个简单的区块

Example 项目有个 block_example 模块,在 src/Plugin/Block 文件夹内有 3 个例子,分别展示 3 种不同区块。
我们看下最简单的那个:创建一个没有任何内容的空块。

首先在 examples  文件夹内创建新模块 block_example(创建模块方法请参考上一课)。
之后在 block_example 目录下创建 src/Plugin/Block 目录。
最后在 Block 目录创建 ExampleEmptyBlock.php 文件,放置代码,见辅助内容区。

<?php

namespace Drupal\block_example\Plugin\Block;
use Drupal\Core\Block\BlockBase;

/**
 * Provides a 'Example: empty block' block.
 *
 * @Block(
 *   id = "example_empty",
 *   admin_label = @Translation("Example: empty block")
 * )
 */
class ExampleEmptyBlock extends BlockBase {

  /**
   * {@inheritdoc}
   */
  public function build() {
    return [
      '#type' => 'markup',
      '#markup' => '',
    ];
  }

}

 

类和注解

所有类开始的时候必须定义名字空间,之后我们扩展 BlockBase 创建类 ExampleEmptyBlock 。 在这个类里我们可以使用 Drupal 8 引入的注解。

通常 PHP 注解是一段自包含的注释文本,它允许类文件注册信息和元数据的自动发现。

上面第 1 组注解是告诉 Drupal 我们要创建一个 id 为 example_empty 和 管理 label 为 “Example: empty block”的区块(@Block)。并且这个管理 label 在使用之前要经过翻译系统处理。

在覆写类函数时可以使用 {@inheritdoc}  注解,它告诉系统这里使用父类的注解。

我们实现了一个 build() 方法,这是一个最重要、常用的方法,它会返回一个可渲染数组(用于块输出)。

确保 block_example 模块被激活,清空缓存。
在块配置页(/admin/structure/block)的任意区域内点击“放置区块”按钮,弹出的对话框内你会看到这个新区块。

注意: 只有书写了正确的注解后 Drupal 才能监测到这个块。

本书共39小节。


评论 (0)