summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwebchick2014-05-06 18:19:21 (GMT)
committerwebchick2014-05-06 18:24:18 (GMT)
commit39edc2708e281a3bb775dfa1d49bb0fe637ba9b7 (patch)
tree2be71422bc197020915b3e248813e10dbc5ea67d
parent26eb01c06de7aea4134674799bbb5a5a56f28291 (diff)
Issue #1871762 by eojthebrave, jibran, xjm: Add detailed documentation explaining the block system's architecture.
-rw-r--r--core/modules/block/lib/Drupal/block/Annotation/Block.php2
-rw-r--r--core/modules/block/lib/Drupal/block/BlockBase.php2
-rw-r--r--core/modules/block/lib/Drupal/block/BlockPluginInterface.php2
-rw-r--r--core/modules/system/core.api.php33
4 files changed, 32 insertions, 7 deletions
diff --git a/core/modules/block/lib/Drupal/block/Annotation/Block.php b/core/modules/block/lib/Drupal/block/Annotation/Block.php
index ec093be..1f043c4 100644
--- a/core/modules/block/lib/Drupal/block/Annotation/Block.php
+++ b/core/modules/block/lib/Drupal/block/Annotation/Block.php
@@ -12,6 +12,8 @@ use Drupal\Component\Annotation\Plugin;
/**
* Defines a Block annotation object.
*
+ * @ingroup block_api
+ *
* @Annotation
*/
class Block extends Plugin {
diff --git a/core/modules/block/lib/Drupal/block/BlockBase.php b/core/modules/block/lib/Drupal/block/BlockBase.php
index 649bafc..e50a18c 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -22,6 +22,8 @@ use Drupal\Core\Session\AccountInterface;
* This abstract class provides the generic block configuration form, default
* block settings, and handling for general user-defined block visibility
* settings.
+ *
+ * @ingroup block_api
*/
abstract class BlockBase extends PluginBase implements BlockPluginInterface {
diff --git a/core/modules/block/lib/Drupal/block/BlockPluginInterface.php b/core/modules/block/lib/Drupal/block/BlockPluginInterface.php
index 4a25093..f45ecc5 100644
--- a/core/modules/block/lib/Drupal/block/BlockPluginInterface.php
+++ b/core/modules/block/lib/Drupal/block/BlockPluginInterface.php
@@ -20,6 +20,8 @@ use Drupal\Core\Session\AccountInterface;
* architecture and the relationships between the various objects, including
* brif references to the important components that are not coupled to the
* interface.
+ *
+ * @ingroup block_api
*/
interface BlockPluginInterface extends ConfigurablePluginInterface, PluginFormInterface, PluginInspectionInterface, CacheableInterface {
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index c8a5ede..f2cc90e 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -68,13 +68,32 @@
* @{
* Information about the classes and interfaces that make up the Block API.
*
- * @todo write this
- *
- * Additional documentation paragraphs need to be written, and classes and
- * interfaces need to be added to this topic.
- *
- * See https://drupal.org/node/2168137
- * @}
+ * 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.
*/
/**