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