Code Coverage for /Users/ericduran/Sites/drupal/drupal/core/lib/Drupal/Core/Block/BlockPluginInterface.php

	Code Coverage
	Classes and Traits		Functions and Methods				Lines
Total	100.00% covered (success)	0 / 0	100.00% covered (success)	100.00%	0 / 0	CRAP	100.00% covered (success)	100.00%	0 / 0

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