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

   1 <?php
   2
   3 namespace Drupal\Core\Block;
   4
   5 use Drupal\Core\Access\AccessResult;
   6 use Drupal\Core\Form\FormStateInterface;
   7 use Drupal\Core\Messenger\MessengerTrait;
   8 use Drupal\Core\Plugin\ContextAwarePluginAssignmentTrait;
   9 use Drupal\Core\Plugin\ContextAwarePluginBase;
  10 use Drupal\Component\Utility\NestedArray;
  11 use Drupal\Core\Language\LanguageInterface;
  12 use Drupal\Core\Plugin\PluginWithFormsInterface;
  13 use Drupal\Core\Plugin\PluginWithFormsTrait;
  14 use Drupal\Core\Session\AccountInterface;
  15 use Drupal\Component\Transliteration\TransliterationInterface;
  16
  17 /**
  18  * Defines a base block implementation that most blocks plugins will extend.
  19  *
  20  * This abstract class provides the generic block configuration form, default
  21  * block settings, and handling for general user-defined block visibility
  22  * settings.
  23  *
  24  * @ingroup block_api
  25  */
  26 abstract class BlockBase extends ContextAwarePluginBase implements BlockPluginInterface, PluginWithFormsInterface {
  27
  28   use ContextAwarePluginAssignmentTrait;
  29   use MessengerTrait;
  30   use PluginWithFormsTrait;
  31
  32   /**
  33    * The transliteration service.
  34    *
  35    * @var \Drupal\Component\Transliteration\TransliterationInterface
  36    */
  37   protected $transliteration;
  38
  39   /**
  40    * {@inheritdoc}
  41    */
  42   public function label() {
  43     if (!empty($this->configuration['label'])) {
  44       return $this->configuration['label'];
  45     }
  46
  47     $definition = $this->getPluginDefinition();
  48     // Cast the admin label to a string since it is an object.
  49     // @see \Drupal\Core\StringTranslation\TranslatableMarkup
  50     return (string) $definition['admin_label'];
  51   }
  52
  53   /**
  54    * {@inheritdoc}
  55    */
  56   public function __construct(array $configuration, $plugin_id, $plugin_definition) {
  57     parent::__construct($configuration, $plugin_id, $plugin_definition);
  58     $this->setConfiguration($configuration);
  59   }
  60
  61   /**
  62    * {@inheritdoc}
  63    */
  64   public function getConfiguration() {
  65     return $this->configuration;
  66   }
  67
  68   /**
  69    * {@inheritdoc}
  70    */
  71   public function setConfiguration(array $configuration) {
  72     $this->configuration = NestedArray::mergeDeep(
  73       $this->baseConfigurationDefaults(),
  74       $this->defaultConfiguration(),
  75       $configuration
  76     );
  77   }
  78
  79   /**
  80    * Returns generic default configuration for block plugins.
  81    *
  82    * @return array
  83    *   An associative array with the default configuration.
  84    */
  85   protected function baseConfigurationDefaults() {
  86     return [
  87       'id' => $this->getPluginId(),
  88       'label' => '',
  89       'provider' => $this->pluginDefinition['provider'],
  90       'label_display' => static::BLOCK_LABEL_VISIBLE,
  91     ];
  92   }
  93
  94   /**
  95    * {@inheritdoc}
  96    */
  97   public function defaultConfiguration() {
  98     return [];
  99   }
 100
 101   /**
 102    * {@inheritdoc}
 103    */
 104   public function setConfigurationValue($key, $value) {
 105     $this->configuration[$key] = $value;
 106   }
 107
 108   /**
 109    * {@inheritdoc}
 110    */
 111   public function calculateDependencies() {
 112     return [];
 113   }
 114
 115   /**
 116    * {@inheritdoc}
 117    */
 118   public function access(AccountInterface $account, $return_as_object = FALSE) {
 119     $access = $this->blockAccess($account);
 120     return $return_as_object ? $access : $access->isAllowed();
 121   }
 122
 123   /**
 124    * Indicates whether the block should be shown.
 125    *
 126    * Blocks with specific access checking should override this method rather
 127    * than access(), in order to avoid repeating the handling of the
 128    * $return_as_object argument.
 129    *
 130    * @param \Drupal\Core\Session\AccountInterface $account
 131    *   The user session for which to check access.
 132    *
 133    * @return \Drupal\Core\Access\AccessResult
 134    *   The access result.
 135    *
 136    * @see self::access()
 137    */
 138   protected function blockAccess(AccountInterface $account) {
 139     // By default, the block is visible.
 140     return AccessResult::allowed();
 141   }
 142
 143   /**
 144    * {@inheritdoc}
 145    *
 146    * Creates a generic configuration form for all block types. Individual
 147    * block plugins can add elements to this form by overriding
 148    * BlockBase::blockForm(). Most block plugins should not override this
 149    * method unless they need to alter the generic form elements.
 150    *
 151    * @see \Drupal\Core\Block\BlockBase::blockForm()
 152    */
 153   public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
 154     $definition = $this->getPluginDefinition();
 155     $form['provider'] = [
 156       '#type' => 'value',
 157       '#value' => $definition['provider'],
 158     ];
 159
 160     $form['admin_label'] = [
 161       '#type' => 'item',
 162       '#title' => $this->t('Block description'),
 163       '#plain_text' => $definition['admin_label'],
 164     ];
 165     $form['label'] = [
 166       '#type' => 'textfield',
 167       '#title' => $this->t('Title'),
 168       '#maxlength' => 255,
 169       '#default_value' => $this->label(),
 170       '#required' => TRUE,
 171     ];
 172     $form['label_display'] = [
 173       '#type' => 'checkbox',
 174       '#title' => $this->t('Display title'),
 175       '#default_value' => ($this->configuration['label_display'] === static::BLOCK_LABEL_VISIBLE),
 176       '#return_value' => static::BLOCK_LABEL_VISIBLE,
 177     ];
 178
 179     // Add context mapping UI form elements.
 180     $contexts = $form_state->getTemporaryValue('gathered_contexts') ?: [];
 181     $form['context_mapping'] = $this->addContextAssignmentElement($this, $contexts);
 182     // Add plugin-specific settings for this block type.
 183     $form += $this->blockForm($form, $form_state);
 184     return $form;
 185   }
 186
 187   /**
 188    * {@inheritdoc}
 189    */
 190   public function blockForm($form, FormStateInterface $form_state) {
 191     return [];
 192   }
 193
 194   /**
 195    * {@inheritdoc}
 196    *
 197    * Most block plugins should not override this method. To add validation
 198    * for a specific block type, override BlockBase::blockValidate().
 199    *
 200    * @see \Drupal\Core\Block\BlockBase::blockValidate()
 201    */
 202   public function validateConfigurationForm(array &$form, FormStateInterface $form_state) {
 203     // Remove the admin_label form item element value so it will not persist.
 204     $form_state->unsetValue('admin_label');
 205
 206     $this->blockValidate($form, $form_state);
 207   }
 208
 209   /**
 210    * {@inheritdoc}
 211    */
 212   public function blockValidate($form, FormStateInterface $form_state) {}
 213
 214   /**
 215    * {@inheritdoc}
 216    *
 217    * Most block plugins should not override this method. To add submission
 218    * handling for a specific block type, override BlockBase::blockSubmit().
 219    *
 220    * @see \Drupal\Core\Block\BlockBase::blockSubmit()
 221    */
 222   public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
 223     // Process the block's submission handling if no errors occurred only.
 224     if (!$form_state->getErrors()) {
 225       $this->configuration['label'] = $form_state->getValue('label');
 226       $this->configuration['label_display'] = $form_state->getValue('label_display');
 227       $this->configuration['provider'] = $form_state->getValue('provider');
 228       $this->blockSubmit($form, $form_state);
 229     }
 230   }
 231
 232   /**
 233    * {@inheritdoc}
 234    */
 235   public function blockSubmit($form, FormStateInterface $form_state) {}
 236
 237   /**
 238    * {@inheritdoc}
 239    */
 240   public function getMachineNameSuggestion() {
 241     $definition = $this->getPluginDefinition();
 242     $admin_label = $definition['admin_label'];
 243
 244     // @todo This is basically the same as what is done in
 245     //   \Drupal\system\MachineNameController::transliterate(), so it might make
 246     //   sense to provide a common service for the two.
 247     $transliterated = $this->transliteration()->transliterate($admin_label, LanguageInterface::LANGCODE_DEFAULT, '_');
 248     $transliterated = mb_strtolower($transliterated);
 249
 250     $transliterated = preg_replace('@[^a-z0-9_.]+@', '', $transliterated);
 251
 252     return $transliterated;
 253   }
 254
 255   /**
 256    * Wraps the transliteration service.
 257    *
 258    * @return \Drupal\Component\Transliteration\TransliterationInterface
 259    */
 260   protected function transliteration() {
 261     if (!$this->transliteration) {
 262       $this->transliteration = \Drupal::transliteration();
 263     }
 264     return $this->transliteration;
 265   }
 266
 267   /**
 268    * Sets the transliteration service.
 269    *
 270    * @param \Drupal\Component\Transliteration\TransliterationInterface $transliteration
 271    *   The transliteration service.
 272    */
 273   public function setTransliteration(TransliterationInterface $transliteration) {
 274     $this->transliteration = $transliteration;
 275   }
 276
 277 }