BlockPluginInterface.php 5.63 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
5
 * Contains \Drupal\Core\Block\BlockPluginInterface.
6 7
 */

8
namespace Drupal\Core\Block;
9

10
use Drupal\Component\Plugin\Context\ContextInterface;
11
use Drupal\Component\Plugin\DerivativeInspectionInterface;
12
use Drupal\Core\Cache\CacheableInterface;
13 14
use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\Component\Plugin\ConfigurablePluginInterface;
15
use Drupal\Core\Form\FormStateInterface;
16
use Drupal\Core\Plugin\PluginFormInterface;
17
use Drupal\Core\Session\AccountInterface;
18

19 20 21 22 23 24 25
/**
 * Defines the required interface for all block plugins.
 *
 * @todo Add detailed documentation here explaining the block system's
 *   architecture and the relationships between the various objects, including
 *   brif references to the important components that are not coupled to the
 *   interface.
26 27
 *
 * @ingroup block_api
28
 */
29
interface BlockPluginInterface extends ConfigurablePluginInterface, PluginFormInterface, PluginInspectionInterface, CacheableInterface, DerivativeInspectionInterface {
30

31 32 33 34 35 36 37 38 39 40 41
  /**
   * Returns the user-facing block label.
   *
   * @todo Provide other specific label-related methods in
   *   https://drupal.org/node/2025649.
   *
   * @return string
   *   The block label.
   */
  public function label();

42 43 44 45 46 47
  /**
   * Indicates whether the block should be shown.
   *
   * This method allows base implementations to add general access restrictions
   * that should apply to all extending block plugins.
   *
48 49 50
   * @param \Drupal\Core\Session\AccountInterface $account
   *   The user session for which to check access.
   *
51 52 53
   * @return bool
   *   TRUE if the block should be shown, or FALSE otherwise.
   *
54
   * @see \Drupal\block\BlockAccessControlHandler
55
   */
56
  public function access(AccountInterface $account);
57 58

  /**
59
   * Builds and returns the renderable array for this block plugin.
60
   *
61 62
   * @return array
   *   A renderable array representing the content of the block.
63
   *
64
   * @see \Drupal\block\BlockViewBuilder
65 66 67 68 69
   */
  public function build();

  /**
   * Sets a particular value in the block settings.
70
   *
71 72 73 74
   * @param string $key
   *   The key of PluginBase::$configuration to set.
   * @param mixed $value
   *   The value to set for the provided key.
75
   *
76 77
   * @todo This doesn't belong here. Move this into a new base class in
   *   http://drupal.org/node/1764380.
78
   * @todo This does not set a value in \Drupal::config(), so the name is confusing.
79 80
   *
   * @see \Drupal\Component\Plugin\PluginBase::$configuration
81
   */
82
  public function setConfigurationValue($key, $value);
83 84

  /**
85 86 87 88
   * Returns the configuration form elements specific to this block plugin.
   *
   * Blocks that need to add form elements to the normal block configuration
   * form should implement this method.
89 90 91
   *
   * @param array $form
   *   The form definition array for the block configuration form.
92 93
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
94
   *
95 96
   * @return array $form
   *   The renderable form array representing the entire configuration form.
97
   */
98
  public function blockForm($form, FormStateInterface $form_state);
99 100

  /**
101 102
   * Adds block type-specific validation for the block form.
   *
103 104 105
   * Note that this method takes the form structure and form state for the full
   * block configuration form as arguments, not just the elements defined in
   * BlockPluginInterface::blockForm().
106 107
   *
   * @param array $form
108
   *   The form definition array for the full block configuration form.
109 110
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
111
   *
112 113
   * @see \Drupal\Core\Block\BlockPluginInterface::blockForm()
   * @see \Drupal\Core\Block\BlockPluginInterface::blockSubmit()
114
   */
115
  public function blockValidate($form, FormStateInterface $form_state);
116 117

  /**
118
   * Adds block type-specific submission handling for the block form.
119
   *
120 121 122
   * Note that this method takes the form structure and form state for the full
   * block configuration form as arguments, not just the elements defined in
   * BlockPluginInterface::blockForm().
123
   *
124 125
   * @param array $form
   *   The form definition array for the full block configuration form.
126 127
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
128
   *
129 130
   * @see \Drupal\Core\Block\BlockPluginInterface::blockForm()
   * @see \Drupal\Core\Block\BlockPluginInterface::blockValidate()
131
   */
132
  public function blockSubmit($form, FormStateInterface $form_state);
133

134 135 136 137 138 139 140 141 142 143 144 145
  /**
   * Suggests a machine name to identify an instance of this block.
   *
   * The block plugin need not verify that the machine name is at all unique. It
   * is only responsible for providing a baseline suggestion; calling code is
   * responsible for ensuring whatever uniqueness is required for the use case.
   *
   * @return string
   *   The suggested machine name.
   */
  public function getMachineNameSuggestion();

146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
  /**
   * Gets conditions for this block.
   *
   * @return \Drupal\Core\Condition\ConditionInterface[]|\Drupal\Core\Condition\ConditionPluginBag
   *   An array or bag of configured condition plugins.
   */
  public function getVisibilityConditions();

  /**
   * Gets a visibility condition plugin instance.
   *
   * @param string $instance_id
   *   The condition plugin instance ID.
   *
   * @return \Drupal\Core\Condition\ConditionInterface
   *   A condition plugin.
   */
  public function getVisibilityCondition($instance_id);

  /**
   * Sets the visibility condition configuration.
   *
   * @param string $instance_id
   *   The condition instance ID.
   * @param array $configuration
   *   The condition configuration.
   *
   * @return $this
   */
  public function setVisibilityConfig($instance_id, array $configuration);

177
}