From b6a4ff8ab7566e9e5b3bcd19912fe152c82d6e8a Mon Sep 17 00:00:00 2001
From: webchick <drupal@webchick.net>
Date: Wed, 25 Jun 2014 14:26:20 -0700
Subject: [PATCH] Issue #2290285 by jhodgdon: Condition plugin classes need
more links/docs.
---
.../Core/Condition/Annotation/Condition.php | 16 +++++-
.../Core/Condition/ConditionInterface.php | 5 ++
.../Core/Condition/ConditionManager.php | 6 +++
.../Core/Condition/ConditionPluginBase.php | 6 +++
core/modules/block/block.api.php | 53 +++++++++++++++++++
core/modules/system/core.api.php | 33 ------------
6 files changed, 85 insertions(+), 34 deletions(-)
diff --git a/core/lib/Drupal/Core/Condition/Annotation/Condition.php b/core/lib/Drupal/Core/Condition/Annotation/Condition.php
index 64b494669def..55834d041c2f 100644
--- a/core/lib/Drupal/Core/Condition/Annotation/Condition.php
+++ b/core/lib/Drupal/Core/Condition/Annotation/Condition.php
@@ -9,7 +9,21 @@
use Drupal\Component\Annotation\Plugin;
/**
- * Defines a condition annotation object.
+ * Defines a condition plugin annotation object.
+ *
+ * Condition plugins provide generalized conditions for use in other
+ * operations, such as conditional block placement.
+ *
+ * Plugin Namespace: Plugin\Condition
+ *
+ * For a working example, see \Drupal\user\Plugin\Condition\UserRole.
+ *
+ * @see \Drupal\Core\Condition\ConditionManager
+ * @see \Drupal\Core\Condition\ConditionInterface
+ * @see \Drupal\Core\Condition\ConditionPluginBase
+ * @see block_api
+ *
+ * @ingroup plugin_api
*
* @Annotation
*/
diff --git a/core/lib/Drupal/Core/Condition/ConditionInterface.php b/core/lib/Drupal/Core/Condition/ConditionInterface.php
index 7b1d412b8a72..fb23fe27e200 100644
--- a/core/lib/Drupal/Core/Condition/ConditionInterface.php
+++ b/core/lib/Drupal/Core/Condition/ConditionInterface.php
@@ -30,6 +30,11 @@
*
* @see \Drupal\Core\TypedData\TypedDataManager::create()
* @see \Drupal\Core\Executable\ExecutableInterface
+ * @see \Drupal\Core\Condition\ConditionManager
+ * @see \Drupal\Core\Condition\Annotation\Condition
+ * @see \Drupal\Core\Condition\ConditionPluginBase
+ *
+ * @ingroup plugin_api
*/
interface ConditionInterface extends ExecutableInterface, PluginFormInterface, ConfigurablePluginInterface, PluginInspectionInterface {
diff --git a/core/lib/Drupal/Core/Condition/ConditionManager.php b/core/lib/Drupal/Core/Condition/ConditionManager.php
index f6f7641e9c1c..e47dd287229d 100644
--- a/core/lib/Drupal/Core/Condition/ConditionManager.php
+++ b/core/lib/Drupal/Core/Condition/ConditionManager.php
@@ -16,6 +16,12 @@
/**
* A plugin manager for condition plugins.
+ *
+ * @see \Drupal\Core\Condition\Annotation\Condition
+ * @see \Drupal\Core\Condition\ConditionInterface
+ * @see \Drupal\Core\Condition\ConditionPluginBase
+ *
+ * @ingroup plugin_api
*/
class ConditionManager extends DefaultPluginManager implements ExecutableManagerInterface {
diff --git a/core/lib/Drupal/Core/Condition/ConditionPluginBase.php b/core/lib/Drupal/Core/Condition/ConditionPluginBase.php
index 279ef0fadf95..221e3b5f0e8c 100644
--- a/core/lib/Drupal/Core/Condition/ConditionPluginBase.php
+++ b/core/lib/Drupal/Core/Condition/ConditionPluginBase.php
@@ -11,6 +11,12 @@
/**
* Provides a basis for fulfilling contexts for condition plugins.
+ *
+ * @see \Drupal\Core\Condition\Annotation\Condition
+ * @see \Drupal\Core\Condition\ConditionInterface
+ * @see \Drupal\Core\Condition\ConditionManager
+ *
+ * @ingroup plugin_api
*/
abstract class ConditionPluginBase extends ExecutablePluginBase implements ConditionInterface {
diff --git a/core/modules/block/block.api.php b/core/modules/block/block.api.php
index 9210f8253637..a0f79bffe722 100644
--- a/core/modules/block/block.api.php
+++ b/core/modules/block/block.api.php
@@ -5,6 +5,56 @@
* Hooks provided by the Block module.
*/
+/**
+ * @defgroup block_api Block API
+ * @{
+ * Information about the classes and interfaces that make up the Block API.
+ *
+ * Blocks are a combination of a configuration entity and a plugin. The
+ * configuration entity stores placement information (theme, region, weight) and
+ * any other configuration that is specific to the block. The block plugin does
+ * the work of rendering the block's content for display.
+ *
+ * To define a block in a module you need to:
+ * - Define a Block plugin by creating a new class that implements the
+ * \Drupal\block\BlockPluginInterface, in namespace Plugin\Block under your
+ * module namespace. For more information about creating plugins, see the
+ * @link plugin_api Plugin API topic. @endlink
+ * - Usually you will want to extend the \Drupal\block\BlockBase class, which
+ * provides a common configuration form and utility methods for getting and
+ * setting configuration in the block configuration entity.
+ * - Block plugins use the annotations defined by
+ * \Drupal\block\Annotation\Block. See the
+ * @link annotation Annotations topic @endlink for more information about
+ * annotations.
+ *
+ * The Block API also makes use of Condition plugins, for conditional block
+ * placement. Condition plugins have interface
+ * \Drupal\Core\Condition\ConditionInterface, base class
+ * \Drupal\Core\Condition\ConditionPluginBase, and go in plugin namespace
+ * Plugin\Condition. Again, see the Plugin API and Annotations topics for
+ * details of how to create a plugin class and annotate it.
+ *
+ * There are also several block-related hooks, which allow you to affect
+ * the content and access permissions for blocks:
+ * - hook_block_view_alter()
+ * - hook_block_view_BASE_BLOCK_ID_alter()
+ * - hook_block_access()
+ *
+ * Further information and examples:
+ * - \Drupal\system\Plugin\Block\SystemPoweredByBlock provides a simple example
+ * of defining a block.
+ * - \Drupal\user\Plugin\Condition\UserRole is a straightforward example of a
+ * block placement condition plugin.
+ * - \Drupal\book\Plugin\Block\BookNavigationBlock is an example of a block with
+ * a custom configuration form.
+ * - For a more in-depth discussion of the Block API see
+ * https://drupal.org/developing/api/8/block_api
+ * - The Examples for Developers project also provides a Block example in
+ * https://drupal.org/project/examples.
+ * @}
+ */
+
/**
* @addtogroup hooks
* @{
@@ -35,6 +85,7 @@
* The block plugin instance.
*
* @see hook_block_view_BASE_BLOCK_ID_alter()
+ * @ingroup block_api
*/
function hook_block_view_alter(array &$build, \Drupal\block\BlockPluginInterface $block) {
// Remove the contextual links on all blocks that provide them.
@@ -62,6 +113,7 @@ function hook_block_view_alter(array &$build, \Drupal\block\BlockPluginInterface
* The block plugin instance.
*
* @see hook_block_view_alter()
+ * @ingroup block_api
*/
function hook_block_view_BASE_BLOCK_ID_alter(array &$build, \Drupal\block\BlockPluginInterface $block) {
// Change the title of the specific block.
@@ -90,6 +142,7 @@ function hook_block_view_BASE_BLOCK_ID_alter(array &$build, \Drupal\block\BlockP
*
* @see \Drupal\Core\Entity\EntityAccessController::access()
* @see \Drupal\block\BlockAccessController::checkAccess()
+ * @ingroup block_api
*/
function hook_block_access(\Drupal\block\Entity\Block $block, $operation, \Drupal\user\Entity\User $account, $langcode) {
// Example code that would prevent displaying the 'Powered by Drupal' block in
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 0e7807babb4f..4b697a1e3ccd 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -66,39 +66,6 @@
* - @link https://drupal.org/developing/api/8 Drupal 8 API longer references @endlink
*/
-/**
- * @defgroup block_api Block API
- * @{
- * Information about the classes and interfaces that make up the Block API.
- *
- * Blocks are a combination of a configuration entity and a plugin. The
- * configuration entity stores placement information (theme, region, weight) and
- * any other configuration that is specific to the block. The block plugin does
- * the work of rendering the block's content for display.
- *
- * To define a block in a module you need to:
- * - Define a Block plugin by creating a new class that implements the
- * \Drupal\block\BlockPluginInterface. For more information about how block
- * plugins are discovered see the @link plugin_api Plugin API topic @endlink.
- * - Usually you will want to extend the \Drupal\block\BlockBase class, which
- * provides a common configuration form and utility methods for getting and
- * setting configuration in the block configuration entity.
- * - Block plugins use the annotations defined by
- * \Drupal\block\Annotation\Block. See the
- * @link annotation Annotations topic @endlink for more information about
- * annotations.
- *
- * Further information and examples:
- * - \Drupal\system\Plugin\Block\SystemPoweredByBlock provides a simple example
- * of defining a block.
- * - \Drupal\book\Plugin\Block\BookNavigationBlock is an example of a block with
- * a custom configuration form.
- * - For a more in-depth discussion of the Block API see
- * https://drupal.org/developing/api/8/block_api
- * - The examples project also provides a Block example in
- * https://drupal.org/project/examples.
- */
-
/**
* @defgroup third_party REST and Application Integration
* @{
--
GitLab