你在这里

Drupal 8 区块 API

原文链接: Block API in Drupal 8

概述

Drupal 8 的区块实际上是由两个独立的API结构组成的,延续了Drupal一直以来的用户体验。这两个API结构分别是:Block Plugin API,一个独立的可复用的API;区块实体API,用于区块控制位置和可见性。

通过Block Plugin API创建区块

在你自定义的模块代码中创建区块需要了解Plugin API,更具体的说是基于注解的插件探测(方式/模式)(原文: Annotations based plugin discovery)。这是Drupal 8用来查找你自定义的区块的机制。

在模块中创建自定义区块包含以下步骤:

让区块对Drupal和用户可见

假设你的模块叫 fax,依照PSR-4标准,你自定义的区块的代码应该放到 fax/src/Plugin/Block/之中,并基于它包含的类来命名。比如类名为 FaxBlock,那么文件层次应该像 fax/src/Plugin/Block/FaxBlock.php这样。

FaxBlock.php中定义一个名为 FaxBlock的类,如下例:

<?php
namespace Drupal\fax\Plugin\Block;
use
Drupal\block\BlockBase;
/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class ChadBlock extends BlockBase {
   
// Override BlockPluginInterface methods here.
}
?>

注解中的'id'属性是你的区块的机读名称,唯一,能被其他代码引用。注解'admin_label'定义了显示名称。

两个最常重写的方法:

BlockPluginInterface::build()- 该方法返回一个渲染后的数组,包含你想要在区块中显示的内容。

BlockPluginInterface::access()- 该方法根据自定逻辑控制区块的可见性。

添加自定义配置选项

你可以通过重写 BlockPluginInterface::blockForm()BlockPluginInterface::blockSubmit()方法,然后使用BlockBase::setConfigurationValue()BlockBase::getConfiguration()方法来添加自定义配置选项到区块当中。

下例,在blockForm()中添加了一个textfield,然后在blockSubmit()方法中保存了用户填入的值。在blockForm()方法中,你可以看到数据是如何被你的代码获取和使用的。

<?php
/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class ChadBlock extends BlockBase {
   
// Access and build methods here ...
  /**
   * {@inheritdoc}
   */
 
public function blockForm($form, &$form_state) {
   
$form = parent::blockForm($form, $form_state);
   
//Retrieve existing configuration for this block.
   
$config = $this->getConfiguration();
   
// Add a form field to the existing block configuration form.
   
$form['fax_block_settings'] = array(
     
'#type' => 'textfield',
     
'#title' => t('Fax number'),
     
'#default_value' => isset($config['fax_block_settings']) ? $config['fax_block_settings'] : '',
    );
    return
$form;
  }
 
/**
   * {@inheritdoc}
   */
 
public function blockSubmit($form, &$form_state) {
     
// Save our custom settings when the form is submitted.
   
$this->setConfigurationValue('fax_block_settings', $form_state['values']['fax_block_settings']);
  }
}
?>

同样,你可以再build()方法中调用BlockBase::getConfiguration()方法来接收配置参数并显示给用户。也可以在access()方法中执行更复杂的逻辑来决定是否显示这些配置参数。