trait BlockPluginTrait

Same name in other branches
  1. 9 core/lib/Drupal/Core/Block/BlockPluginTrait.php \Drupal\Core\Block\BlockPluginTrait
  2. 8.9.x core/lib/Drupal/Core/Block/BlockPluginTrait.php \Drupal\Core\Block\BlockPluginTrait
  3. 11.x core/lib/Drupal/Core/Block/BlockPluginTrait.php \Drupal\Core\Block\BlockPluginTrait

Provides the base implementation of a block plugin.

@internal This trait is used internally by the block system. Block plugins should extend \Drupal\Core\Block\BlockBase.

Hierarchy

See also

\Drupal\Core\Block\BlockBase

\Drupal\Core\Block\BlockPluginInterface

Related topics

1 file declares its use of BlockPluginTrait
Broken.php in core/lib/Drupal/Core/Block/Plugin/Block/Broken.php

File

core/lib/Drupal/Core/Block/BlockPluginTrait.php, line 27

Namespace

Drupal\Core\Block
View source
trait BlockPluginTrait {
    use StringTranslationTrait;
    use MessengerTrait;
    use PluginWithFormsTrait;
    
    /**
     * Whether the plugin is being rendered in preview mode.
     *
     * @var bool
     */
    protected $inPreview = FALSE;
    
    /**
     * The transliteration service.
     *
     * @var \Drupal\Component\Transliteration\TransliterationInterface
     */
    protected $transliteration;
    
    /**
     * {@inheritdoc}
     */
    public function label() {
        if (!empty($this->configuration['label'])) {
            return $this->configuration['label'];
        }
        $definition = $this->getPluginDefinition();
        // Cast the admin label to a string since it is an object.
        // @see \Drupal\Core\StringTranslation\TranslatableMarkup
        return (string) $definition['admin_label'];
    }
    
    /**
     * {@inheritdoc}
     */
    public function __construct(array $configuration, $plugin_id, $plugin_definition) {
        parent::__construct($configuration, $plugin_id, $plugin_definition);
        $this->setConfiguration($configuration);
    }
    
    /**
     * {@inheritdoc}
     */
    public function getConfiguration() {
        return $this->configuration;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setConfiguration(array $configuration) {
        $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() {
        return [
            'id' => $this->getPluginId(),
            'label' => '',
            'label_display' => BlockPluginInterface::BLOCK_LABEL_VISIBLE,
            'provider' => $this->pluginDefinition['provider'],
        ];
    }
    
    /**
     * {@inheritdoc}
     */
    public function defaultConfiguration() {
        return [];
    }
    
    /**
     * {@inheritdoc}
     */
    public function setConfigurationValue($key, $value) {
        $this->configuration[$key] = $value;
    }
    
    /**
     * {@inheritdoc}
     */
    public function calculateDependencies() {
        return [];
    }
    
    /**
     * {@inheritdoc}
     */
    public function access(AccountInterface $account, $return_as_object = FALSE) {
        $access = $this->blockAccess($account);
        return $return_as_object ? $access : $access->isAllowed();
    }
    
    /**
     * Indicates whether the block should be shown.
     *
     * 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.
     *
     * @param \Drupal\Core\Session\AccountInterface $account
     *   The user session for which to check access.
     *
     * @return \Drupal\Core\Access\AccessResultInterface
     *   The access result.
     *
     * @see self::access()
     */
    protected function blockAccess(AccountInterface $account) {
        // By default, the block is visible.
        return AccessResult::allowed();
    }
    
    /**
     * {@inheritdoc}
     *
     * 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.
     *
     * @see \Drupal\Core\Block\BlockBase::blockForm()
     */
    public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
        $definition = $this->getPluginDefinition();
        $form['provider'] = [
            '#type' => 'value',
            '#value' => $definition['provider'],
        ];
        $form['admin_label'] = [
            '#type' => 'item',
            '#title' => $this->t('Block description'),
            '#plain_text' => $definition['admin_label'],
        ];
        $form['label'] = [
            '#type' => 'textfield',
            '#title' => $this->t('Title'),
            '#maxlength' => 255,
            '#default_value' => $this->label(),
            '#required' => TRUE,
        ];
        $form['label_display'] = [
            '#type' => 'checkbox',
            '#title' => $this->t('Display title'),
            '#default_value' => $this->configuration['label_display'] === BlockPluginInterface::BLOCK_LABEL_VISIBLE,
            '#return_value' => BlockPluginInterface::BLOCK_LABEL_VISIBLE,
        ];
        // Add plugin-specific settings for this block type.
        $form += $this->blockForm($form, $form_state);
        return $form;
    }
    
    /**
     * {@inheritdoc}
     */
    public function blockForm($form, FormStateInterface $form_state) {
        return [];
    }
    
    /**
     * {@inheritdoc}
     *
     * Most block plugins should not override this method. To add validation
     * for a specific block type, override BlockBase::blockValidate().
     *
     * @see \Drupal\Core\Block\BlockBase::blockValidate()
     */
    public function validateConfigurationForm(array &$form, FormStateInterface $form_state) {
        // Remove the admin_label form item element value so it will not persist.
        $form_state->unsetValue('admin_label');
        $this->blockValidate($form, $form_state);
    }
    
    /**
     * {@inheritdoc}
     */
    public function blockValidate($form, FormStateInterface $form_state) {
    }
    
    /**
     * {@inheritdoc}
     *
     * Most block plugins should not override this method. To add submission
     * handling for a specific block type, override BlockBase::blockSubmit().
     *
     * @see \Drupal\Core\Block\BlockBase::blockSubmit()
     */
    public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
        // Process the block's submission handling if no errors occurred only.
        if (!$form_state->getErrors()) {
            $this->configuration['label'] = $form_state->getValue('label');
            $this->configuration['label_display'] = $form_state->getValue('label_display');
            $this->configuration['provider'] = $form_state->getValue('provider');
            $this->blockSubmit($form, $form_state);
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function blockSubmit($form, FormStateInterface $form_state) {
    }
    
    /**
     * {@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.
        $transliterated = $this->transliteration()
            ->transliterate($admin_label, LanguageInterface::LANGCODE_DEFAULT, '_');
        $transliterated = mb_strtolower($transliterated);
        $transliterated = preg_replace('@[^a-z0-9_.]+@', '', $transliterated);
        // Furthermore remove any characters that are not alphanumerical from the
        // beginning and end of the transliterated string.
        $transliterated = preg_replace('@^([^a-z0-9]+)|([^a-z0-9]+)$@', '', $transliterated);
        return $transliterated;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getPreviewFallbackString() {
        return $this->t('"@block" block', [
            '@block' => $this->label(),
        ]);
    }
    
    /**
     * 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;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setInPreview(bool $in_preview) : void {
        $this->inPreview = $in_preview;
    }

}

Members

Title Sort descending Modifiers Object type Summary Overrides
BlockPluginTrait::$inPreview protected property Whether the plugin is being rendered in preview mode.
BlockPluginTrait::$transliteration protected property The transliteration service.
BlockPluginTrait::access public function
BlockPluginTrait::baseConfigurationDefaults protected function Returns generic default configuration for block plugins.
BlockPluginTrait::blockAccess protected function Indicates whether the block should be shown. 18
BlockPluginTrait::blockForm public function 16
BlockPluginTrait::blockSubmit public function 12
BlockPluginTrait::blockValidate public function 3
BlockPluginTrait::buildConfigurationForm public function 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.
BlockPluginTrait::calculateDependencies public function 1
BlockPluginTrait::defaultConfiguration public function 18
BlockPluginTrait::getConfiguration public function 1
BlockPluginTrait::getMachineNameSuggestion public function 1
BlockPluginTrait::getPreviewFallbackString public function 3
BlockPluginTrait::label public function
BlockPluginTrait::setConfiguration public function
BlockPluginTrait::setConfigurationValue public function
BlockPluginTrait::setInPreview public function
BlockPluginTrait::setTransliteration public function Sets the transliteration service.
BlockPluginTrait::submitConfigurationForm public function Most block plugins should not override this method. To add submission
handling for a specific block type, override BlockBase::blockSubmit().
BlockPluginTrait::transliteration protected function Wraps the transliteration service.
BlockPluginTrait::validateConfigurationForm public function Most block plugins should not override this method. To add validation
for a specific block type, override BlockBase::blockValidate().
1
BlockPluginTrait::__construct public function 26
MessengerTrait::$messenger protected property The messenger. 16
MessengerTrait::messenger public function Gets the messenger. 16
MessengerTrait::setMessenger public function Sets the messenger.
PluginWithFormsTrait::getFormClass public function Implements \Drupal\Core\Plugin\PluginWithFormsInterface::getFormClass().
PluginWithFormsTrait::hasFormClass public function Implements \Drupal\Core\Plugin\PluginWithFormsInterface::hasFormClass().
StringTranslationTrait::$stringTranslation protected property The string translation service. 3
StringTranslationTrait::formatPlural protected function Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals protected function Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation protected function Gets the string translation service.
StringTranslationTrait::setStringTranslation public function Sets the string translation service to use. 2
StringTranslationTrait::t protected function Translates a string to the current language or to a given language.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.