123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156 |
- <?php
- namespace Drupal\Core\Block;
- use Drupal\Component\Plugin\DerivativeInspectionInterface;
- use Drupal\Core\Cache\CacheableDependencyInterface;
- use Drupal\Component\Plugin\PluginInspectionInterface;
- use Drupal\Component\Plugin\ConfigurablePluginInterface;
- use Drupal\Core\Form\FormStateInterface;
- use Drupal\Core\Plugin\PluginFormInterface;
- use Drupal\Core\Session\AccountInterface;
- /**
- * 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
- * brief references to the important components that are not coupled to the
- * interface.
- *
- * @ingroup block_api
- */
- interface BlockPluginInterface extends ConfigurablePluginInterface, PluginFormInterface, PluginInspectionInterface, CacheableDependencyInterface, DerivativeInspectionInterface {
- /**
- * Indicates the block label (title) should be displayed to end users.
- */
- const BLOCK_LABEL_VISIBLE = 'visible';
- /**
- * Returns the user-facing block label.
- *
- * @todo Provide other specific label-related methods in
- * https://www.drupal.org/node/2025649.
- *
- * @return string
- * The block label.
- */
- public function label();
- /**
- * 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.
- *
- * @param \Drupal\Core\Session\AccountInterface $account
- * The user session for which to check access.
- * @param bool $return_as_object
- * (optional) Defaults to FALSE.
- *
- * @return bool|\Drupal\Core\Access\AccessResultInterface
- * The access result. Returns a boolean if $return_as_object is FALSE (this
- * is the default) and otherwise an AccessResultInterface object.
- * When a boolean is returned, the result of AccessInterface::isAllowed() is
- * returned, i.e. TRUE means access is explicitly allowed, FALSE means
- * access is either explicitly forbidden or "no opinion".
- *
- * @see \Drupal\block\BlockAccessControlHandler
- */
- public function access(AccountInterface $account, $return_as_object = FALSE);
- /**
- * Builds and returns the renderable array for this block plugin.
- *
- * If a block should not be rendered because it has no content, then this
- * method must also ensure to return no content: it must then only return an
- * empty array, or an empty array with #cache set (with cacheability metadata
- * indicating the circumstances for it being empty).
- *
- * @return array
- * A renderable array representing the content of the block.
- *
- * @see \Drupal\block\BlockViewBuilder
- */
- public function build();
- /**
- * Sets a particular value in the block settings.
- *
- * @param string $key
- * The key of PluginBase::$configuration to set.
- * @param mixed $value
- * The value to set for the provided key.
- *
- * @todo This doesn't belong here. Move this into a new base class in
- * https://www.drupal.org/node/1764380.
- * @todo This does not set a value in \Drupal::config(), so the name is confusing.
- *
- * @see \Drupal\Component\Plugin\PluginBase::$configuration
- */
- public function setConfigurationValue($key, $value);
- /**
- * 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.
- *
- * @param array $form
- * The form definition array for the block configuration form.
- * @param \Drupal\Core\Form\FormStateInterface $form_state
- * The current state of the form.
- *
- * @return array
- * The renderable form array representing the entire configuration form.
- */
- public function blockForm($form, FormStateInterface $form_state);
- /**
- * Adds block type-specific validation for the block form.
- *
- * 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().
- *
- * @param array $form
- * The form definition array for the full block configuration form.
- * @param \Drupal\Core\Form\FormStateInterface $form_state
- * The current state of the form.
- *
- * @see \Drupal\Core\Block\BlockPluginInterface::blockForm()
- * @see \Drupal\Core\Block\BlockPluginInterface::blockSubmit()
- */
- public function blockValidate($form, FormStateInterface $form_state);
- /**
- * Adds block type-specific submission handling for the block form.
- *
- * 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().
- *
- * @param array $form
- * The form definition array for the full block configuration form.
- * @param \Drupal\Core\Form\FormStateInterface $form_state
- * The current state of the form.
- *
- * @see \Drupal\Core\Block\BlockPluginInterface::blockForm()
- * @see \Drupal\Core\Block\BlockPluginInterface::blockValidate()
- */
- public function blockSubmit($form, FormStateInterface $form_state);
- /**
- * 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();
- }
|