annotate core/lib/Drupal/Core/Block/BlockPluginInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
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 }