Commit 39edc270 authored by webchick's avatar webchick

Issue #1871762 by eojthebrave, jibran, xjm: Add detailed documentation...

Issue #1871762 by eojthebrave, jibran, xjm: Add detailed documentation explaining the block system's architecture.
parent 26eb01c0
......@@ -12,6 +12,8 @@
/**
* Defines a Block annotation object.
*
* @ingroup block_api
*
* @Annotation
*/
class Block extends Plugin {
......
......@@ -22,6 +22,8 @@
* 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 {
......
......@@ -20,6 +20,8 @@
* 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 {
......
......@@ -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.
*/
/**
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment