BlockBase.php 8.19 KB
Newer Older
1 2
<?php

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\Render\PlaceholderInterface;
15
use Drupal\Core\Session\AccountInterface;
16
use Drupal\Component\Transliteration\TransliterationInterface;
17 18 19 20 21 22 23

/**
 * Defines a base block implementation that most blocks plugins will extend.
 *
 * This abstract class provides the generic block configuration form, default
 * block settings, and handling for general user-defined block visibility
 * settings.
24 25
 *
 * @ingroup block_api
26
 */
27
abstract class BlockBase extends ContextAwarePluginBase implements BlockPluginInterface, PluginWithFormsInterface, PlaceholderInterface {
28

29
  use ContextAwarePluginAssignmentTrait;
30
  use MessengerTrait;
31
  use PluginWithFormsTrait;
32

33 34 35 36 37 38 39
  /**
   * The transliteration service.
   *
   * @var \Drupal\Component\Transliteration\TransliterationInterface
   */
  protected $transliteration;

40 41 42 43 44 45 46 47 48
  /**
   * {@inheritdoc}
   */
  public function label() {
    if (!empty($this->configuration['label'])) {
      return $this->configuration['label'];
    }

    $definition = $this->getPluginDefinition();
49
    // Cast the admin label to a string since it is an object.
50
    // @see \Drupal\Core\StringTranslation\TranslatableMarkup
51
    return (string) $definition['admin_label'];
52 53
  }

54
  /**
55
   * {@inheritdoc}
56
   */
57
  public function __construct(array $configuration, $plugin_id, $plugin_definition) {
58
    parent::__construct($configuration, $plugin_id, $plugin_definition);
59
    $this->setConfiguration($configuration);
60 61 62
  }

  /**
63
   * {@inheritdoc}
64
   */
65
  public function getConfiguration() {
66
    return $this->configuration;
67 68 69
  }

  /**
70 71 72
   * {@inheritdoc}
   */
  public function setConfiguration(array $configuration) {
73 74 75 76 77 78 79 80 81 82 83 84 85 86
    $this->configuration = NestedArray::mergeDeep(
      $this->baseConfigurationDefaults(),
      $this->defaultConfiguration(),
      $configuration
    );
  }

  /**
   * Returns generic default configuration for block plugins.
   *
   * @return array
   *   An associative array with the default configuration.
   */
  protected function baseConfigurationDefaults() {
87
    return [
88
      'id' => $this->getPluginId(),
89
      'label' => '',
90
      'provider' => $this->pluginDefinition['provider'],
91
      'label_display' => static::BLOCK_LABEL_VISIBLE,
92
    ];
93 94
  }

95 96 97 98
  /**
   * {@inheritdoc}
   */
  public function defaultConfiguration() {
99
    return [];
100 101
  }

102 103
  /**
   * {@inheritdoc}
104
   */
105
  public function setConfigurationValue($key, $value) {
106 107 108
    $this->configuration[$key] = $value;
  }

109 110 111 112
  /**
   * {@inheritdoc}
   */
  public function calculateDependencies() {
113
    return [];
114 115
  }

116
  /**
117
   * {@inheritdoc}
118
   */
119
  public function access(AccountInterface $account, $return_as_object = FALSE) {
120
    $access = $this->blockAccess($account);
121
    return $return_as_object ? $access : $access->isAllowed();
122 123 124 125 126
  }

  /**
   * Indicates whether the block should be shown.
   *
127 128 129 130
   * Blocks with specific access checking should override this method rather
   * than access(), in order to avoid repeating the handling of the
   * $return_as_object argument.
   *
131 132 133
   * @param \Drupal\Core\Session\AccountInterface $account
   *   The user session for which to check access.
   *
134 135
   * @return \Drupal\Core\Access\AccessResult
   *   The access result.
136 137 138 139 140
   *
   * @see self::access()
   */
  protected function blockAccess(AccountInterface $account) {
    // By default, the block is visible.
141
    return AccessResult::allowed();
142 143 144
  }

  /**
145
   * {@inheritdoc}
146 147 148 149 150 151
   *
   * Creates a generic configuration form for all block types. Individual
   * block plugins can add elements to this form by overriding
   * BlockBase::blockForm(). Most block plugins should not override this
   * method unless they need to alter the generic form elements.
   *
152
   * @see \Drupal\Core\Block\BlockBase::blockForm()
153
   */
154
  public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
155
    $definition = $this->getPluginDefinition();
156
    $form['provider'] = [
157
      '#type' => 'value',
158
      '#value' => $definition['provider'],
159
    ];
160

161
    $form['admin_label'] = [
162
      '#type' => 'item',
163
      '#title' => $this->t('Block description'),
164
      '#plain_text' => $definition['admin_label'],
165 166
    ];
    $form['label'] = [
167
      '#type' => 'textfield',
168
      '#title' => $this->t('Title'),
169
      '#maxlength' => 255,
170
      '#default_value' => $this->label(),
171
      '#required' => TRUE,
172 173
    ];
    $form['label_display'] = [
174
      '#type' => 'checkbox',
175
      '#title' => $this->t('Display title'),
176 177
      '#default_value' => ($this->configuration['label_display'] === static::BLOCK_LABEL_VISIBLE),
      '#return_value' => static::BLOCK_LABEL_VISIBLE,
178
    ];
179

180 181 182
    // Add context mapping UI form elements.
    $contexts = $form_state->getTemporaryValue('gathered_contexts') ?: [];
    $form['context_mapping'] = $this->addContextAssignmentElement($this, $contexts);
183
    // Add plugin-specific settings for this block type.
184
    $form += $this->blockForm($form, $form_state);
185 186 187 188
    return $form;
  }

  /**
189
   * {@inheritdoc}
190
   */
191
  public function blockForm($form, FormStateInterface $form_state) {
192
    return [];
193 194 195
  }

  /**
196
   * {@inheritdoc}
197 198
   *
   * Most block plugins should not override this method. To add validation
199
   * for a specific block type, override BlockBase::blockValidate().
200
   *
201
   * @see \Drupal\Core\Block\BlockBase::blockValidate()
202
   */
203
  public function validateConfigurationForm(array &$form, FormStateInterface $form_state) {
204
    // Remove the admin_label form item element value so it will not persist.
205
    $form_state->unsetValue('admin_label');
206

207 208 209 210
    $this->blockValidate($form, $form_state);
  }

  /**
211
   * {@inheritdoc}
212
   */
213
  public function blockValidate($form, FormStateInterface $form_state) {}
214 215

  /**
216
   * {@inheritdoc}
217 218 219 220
   *
   * Most block plugins should not override this method. To add submission
   * handling for a specific block type, override BlockBase::blockSubmit().
   *
221
   * @see \Drupal\Core\Block\BlockBase::blockSubmit()
222
   */
223
  public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
224
    // Process the block's submission handling if no errors occurred only.
225
    if (!$form_state->getErrors()) {
226 227 228
      $this->configuration['label'] = $form_state->getValue('label');
      $this->configuration['label_display'] = $form_state->getValue('label_display');
      $this->configuration['provider'] = $form_state->getValue('provider');
229 230 231 232 233
      $this->blockSubmit($form, $form_state);
    }
  }

  /**
234
   * {@inheritdoc}
235
   */
236
  public function blockSubmit($form, FormStateInterface $form_state) {}
237

238 239 240 241 242 243 244 245 246 247
  /**
   * {@inheritdoc}
   */
  public function getMachineNameSuggestion() {
    $definition = $this->getPluginDefinition();
    $admin_label = $definition['admin_label'];

    // @todo This is basically the same as what is done in
    //   \Drupal\system\MachineNameController::transliterate(), so it might make
    //   sense to provide a common service for the two.
248
    $transliterated = $this->transliteration()->transliterate($admin_label, LanguageInterface::LANGCODE_DEFAULT, '_');
249
    $transliterated = mb_strtolower($transliterated);
250

251
    $transliterated = preg_replace('@[^a-z0-9_.]+@', '', $transliterated);
252 253 254 255

    return $transliterated;
  }

256 257 258 259 260 261 262
  /**
   * {@inheritdoc}
   */
  public function getPlaceholderString() {
    return $this->t('Placeholder for the "@block" block', ['@block' => $this->label()]);
  }

263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
  /**
   * Wraps the transliteration service.
   *
   * @return \Drupal\Component\Transliteration\TransliterationInterface
   */
  protected function transliteration() {
    if (!$this->transliteration) {
      $this->transliteration = \Drupal::transliteration();
    }
    return $this->transliteration;
  }

  /**
   * Sets the transliteration service.
   *
   * @param \Drupal\Component\Transliteration\TransliterationInterface $transliteration
   *   The transliteration service.
   */
  public function setTransliteration(TransliterationInterface $transliteration) {
    $this->transliteration = $transliteration;
  }

285
}