www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Block/BlockPluginInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Block;
   4
   5 use Drupal\Component\Plugin\DerivativeInspectionInterface;
   6 use Drupal\Core\Cache\CacheableDependencyInterface;
   7 use Drupal\Component\Plugin\PluginInspectionInterface;
   8 use Drupal\Component\Plugin\ConfigurablePluginInterface;
   9 use Drupal\Core\Form\FormStateInterface;
  10 use Drupal\Core\Plugin\PluginFormInterface;
  11 use Drupal\Core\Session\AccountInterface;
  12
  13 /**
  14  * Defines the required interface for all block plugins.
  15  *
  16  * @todo Add detailed documentation here explaining the block system's
  17  *   architecture and the relationships between the various objects, including
  18  *   brief references to the important components that are not coupled to the
  19  *   interface.
  20  *
  21  * @ingroup block_api
  22  */
  23 interface BlockPluginInterface extends ConfigurablePluginInterface, PluginFormInterface, PluginInspectionInterface, CacheableDependencyInterface, DerivativeInspectionInterface {
  24
  25   /**
  26    * Indicates the block label (title) should be displayed to end users.
  27    */
  28   const BLOCK_LABEL_VISIBLE = 'visible';
  29
  30   /**
  31    * Returns the user-facing block label.
  32    *
  33    * @todo Provide other specific label-related methods in
  34    *   https://www.drupal.org/node/2025649.
  35    *
  36    * @return string
  37    *   The block label.
  38    */
  39   public function label();
  40
  41   /**
  42    * Indicates whether the block should be shown.
  43    *
  44    * This method allows base implementations to add general access restrictions
  45    * that should apply to all extending block plugins.
  46    *
  47    * @param \Drupal\Core\Session\AccountInterface $account
  48    *   The user session for which to check access.
  49    * @param bool $return_as_object
  50    *   (optional) Defaults to FALSE.
  51    *
  52    * @return bool|\Drupal\Core\Access\AccessResultInterface
  53    *   The access result. Returns a boolean if $return_as_object is FALSE (this
  54    *   is the default) and otherwise an AccessResultInterface object.
  55    *   When a boolean is returned, the result of AccessInterface::isAllowed() is
  56    *   returned, i.e. TRUE means access is explicitly allowed, FALSE means
  57    *   access is either explicitly forbidden or "no opinion".
  58    *
  59    * @see \Drupal\block\BlockAccessControlHandler
  60    */
  61   public function access(AccountInterface $account, $return_as_object = FALSE);
  62
  63   /**
  64    * Builds and returns the renderable array for this block plugin.
  65    *
  66    * If a block should not be rendered because it has no content, then this
  67    * method must also ensure to return no content: it must then only return an
  68    * empty array, or an empty array with #cache set (with cacheability metadata
  69    * indicating the circumstances for it being empty).
  70    *
  71    * @return array
  72    *   A renderable array representing the content of the block.
  73    *
  74    * @see \Drupal\block\BlockViewBuilder
  75    */
  76   public function build();
  77
  78   /**
  79    * Sets a particular value in the block settings.
  80    *
  81    * @param string $key
  82    *   The key of PluginBase::$configuration to set.
  83    * @param mixed $value
  84    *   The value to set for the provided key.
  85    *
  86    * @todo This doesn't belong here. Move this into a new base class in
  87    *   https://www.drupal.org/node/1764380.
  88    * @todo This does not set a value in \Drupal::config(), so the name is confusing.
  89    *
  90    * @see \Drupal\Component\Plugin\PluginBase::$configuration
  91    */
  92   public function setConfigurationValue($key, $value);
  93
  94   /**
  95    * Returns the configuration form elements specific to this block plugin.
  96    *
  97    * Blocks that need to add form elements to the normal block configuration
  98    * form should implement this method.
  99    *
 100    * @param array $form
 101    *   The form definition array for the block configuration form.
 102    * @param \Drupal\Core\Form\FormStateInterface $form_state
 103    *   The current state of the form.
 104    *
 105    * @return array
 106    *   The renderable form array representing the entire configuration form.
 107    */
 108   public function blockForm($form, FormStateInterface $form_state);
 109
 110   /**
 111    * Adds block type-specific validation for the block form.
 112    *
 113    * Note that this method takes the form structure and form state for the full
 114    * block configuration form as arguments, not just the elements defined in
 115    * BlockPluginInterface::blockForm().
 116    *
 117    * @param array $form
 118    *   The form definition array for the full block configuration form.
 119    * @param \Drupal\Core\Form\FormStateInterface $form_state
 120    *   The current state of the form.
 121    *
 122    * @see \Drupal\Core\Block\BlockPluginInterface::blockForm()
 123    * @see \Drupal\Core\Block\BlockPluginInterface::blockSubmit()
 124    */
 125   public function blockValidate($form, FormStateInterface $form_state);
 126
 127   /**
 128    * Adds block type-specific submission handling for the block form.
 129    *
 130    * Note that this method takes the form structure and form state for the full
 131    * block configuration form as arguments, not just the elements defined in
 132    * BlockPluginInterface::blockForm().
 133    *
 134    * @param array $form
 135    *   The form definition array for the full block configuration form.
 136    * @param \Drupal\Core\Form\FormStateInterface $form_state
 137    *   The current state of the form.
 138    *
 139    * @see \Drupal\Core\Block\BlockPluginInterface::blockForm()
 140    * @see \Drupal\Core\Block\BlockPluginInterface::blockValidate()
 141    */
 142   public function blockSubmit($form, FormStateInterface $form_state);
 143
 144   /**
 145    * Suggests a machine name to identify an instance of this block.
 146    *
 147    * The block plugin need not verify that the machine name is at all unique. It
 148    * is only responsible for providing a baseline suggestion; calling code is
 149    * responsible for ensuring whatever uniqueness is required for the use case.
 150    *
 151    * @return string
 152    *   The suggested machine name.
 153    */
 154   public function getMachineNameSuggestion();
 155
 156 }