API de Bloques

Resumen

Los bloques en Drupal 8 en realidad consisten en dos estructuras API separadas para crear una interfaz de usuario similar a la que Drupal ha soportado en versiones anteriores. Estas dos APIs son: Block Plugin API, que es una API independiente para reutilización múltiple, y Block Entity API, que es una variante específica en Drupal 8 para la colocación de bloques y control de visibilidad.

Creación de bloques con Block Plugin API

Crear bloques definidos en el código de tu módulo requiere aprender y entender la API de plugins y, en particular, la detección basada en anotaciones, que es el mecanismo que Drupal 8 utiliza para descubrir el código que define tu bloque.

Crear un bloque personalizado definido por tu módulo incluye los siguientes pasos:

• Crear un plugin de bloque usando anotaciones
• Extender la clase Drupal\Core\Block\BlockBase
• Implementar los métodos de la interfaz Drupal\Core\Block\BlockPluginInterface que necesites para tu caso de uso.

Haz tu bloque visible para Drupal y tus usuarios

Drupal utiliza el estándar PSR-4 para la detección. Suponiendo que tu módulo se llama fax, el código para tus bloques personalizados debe colocarse en fax/src/Plugin/Block/. Cada archivo en este directorio debe nombrarse acorde a la clase que contiene. Por ejemplo, si defines la clase FaxBlock, debe estar en el archivo fax/src/Plugin/Block/FaxBlock.php con el siguiente contenido de ejemplo:

namespace Drupal\fax\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Proporciona un bloque 'Fax'.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Bloque Fax"),
 * )
 */
class FaxBlock extends BlockBase {
  // Sobrescribe métodos de BlockPluginInterface aquí.
}

La propiedad id en la anotación define un identificador único legible por máquina para tu bloque y el nombre del bloque que será visible para otro código. La anotación 'admin_label' define el nombre legible que se usará para mostrar el bloque en la interfaz administrativa. Las propiedades disponibles para la anotación se pueden encontrar en \Drupal\Core\Block\Annotation\Block (propiedades públicas).

Los dos métodos más comunes para sobrescribir son:

• BlockPluginInterface::build() — debe devolver un array de renderizado que defina el contenido que quieres que tu bloque muestre.
• BlockBase::access() — controla la visibilidad del bloque. Se espera que retorne un objeto AccessResult.

Agregar parámetros de configuración personalizados a tu bloque

También puedes agregar parámetros de configuración personalizados al formulario de configuración del bloque sobrescribiendo los métodos BlockPluginInterface::blockForm() y BlockPluginInterface::blockSubmit(), y usando BlockBase::setConfigurationValue() y BlockBase::getConfiguration().

En el siguiente ejemplo añadimos un nuevo campo de texto en blockForm() y guardamos los datos proporcionados por el usuario en blockSubmit(). El código muestra cómo obtener valores al construir el formulario, validarlos y actualizarlos usando los métodos apropiados.

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Block\BlockPluginInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Cache\Cache;

/**
 * Proporciona un bloque 'Fax'.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Bloque Fax"),
 * )
 */
class FaxBlock extends BlockBase implements BlockPluginInterface {

  // Método access aquí ...

  /**
   * {@inheritdoc}
   */
  public function build() {
    $config = $this->getConfiguration();
    $fax_number = isset($config['fax_number']) ? $config['fax_number'] : '';
    return [
      '#markup' => $this->t('¡El número de fax es @number!', ['@number' => $fax_number]),
    ];  
  }

  /**
   * {@inheritdoc}
   */
  public function blockForm($form, FormStateInterface $form_state) {
    $form = parent::blockForm($form, $form_state);

    // Recuperar configuración existente para este bloque.
    $config = $this->getConfiguration();

    // Añadir un campo al formulario de configuración del bloque.
    $form['fax_number'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Número de fax'),
      '#default_value' => isset($config['fax_number']) ? $config['fax_number'] : '',
    ];

    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function blockSubmit($form, FormStateInterface $form_state) {
    // Guardar configuración personalizada cuando se envía el formulario.
    $this->setConfigurationValue('fax_number', $form_state->getValue('fax_number'));
  }

  /**
   * {@inheritdoc}
   */
  public function blockValidate($form, FormStateInterface $form_state) {
    $fax_number = $form_state->getValue('fax_number');

    if (!is_numeric($fax_number)) {
      $form_state->setErrorByName('fax_number', $this->t('Debe ser un número entero'));
    }
  }
}

También puedes usar el método BlockBase::getConfiguration() en build() para obtener datos de configuración y mostrarlos a los usuarios. El método access() de tu bloque puede contener lógica más compleja para determinar si el bloque debe mostrarse.

Ejemplo del método de condición de acceso.

/**
 * {@inheritdoc}
 */
public function access(AccountInterface $account, $return_as_object = FALSE) {
  return \Drupal\Core\Access\AccessResult::allowedIf($account->isAuthenticated());
}

También puedes crear tus propias condiciones de caché.

Ejemplo de método que utiliza etiquetas de caché. Aprende más sobre etiquetas de caché.

/**
 * {@inheritdoc}
 */
public function getCacheTags() {
  return \Drupal\Core\Cache\Cache::mergeTags(parent::getCacheTags(), ['node_list']);
}

Si quieres cambiar el máximo tiempo de caché del bloque a 0, más información sobre max-age de caché.

public function getCacheMaxAge() {
  // Si deseas deshabilitar el cacheo para este bloque.
  return 0;
}