Drupal 8 Block Plugin API

This blog post takes a look at how a module developer might create custom blocks in Drupal 8. This is my first attempt at working through all of this so if you've got thoughts on better ways to do this please leave a comment.

Why Blocks?
The concept of blocks has been around in Drupal since the earliest versions. Chunks of information that can be placed into the regions provided by a theme and re-used throughout your site. As Kyle points out in his previous blog post, blocks are really useful in Drupal 8 as the tools for managing their placement and visibility have continued to mature. The system for defining blocks in code has changed quite a bit for Drupal 8 though so it's worth taking a fresh look at how to create blocks in your own module. Especially since in my experience it's one of the first things we need to know how to do as module developers.

Creating Blocks: The Block Plugin API
In previous versions of Drupal, blocks where added by implementing hook_block_info() and the various block CRUD hooks like hook_block_save(). Or if you're really old-school there was just plain ole' hook_block(). The general premises was write some code that tells Drupal about the existence of your block and which PHP functions Drupal should call when someone is viewing the block. Then implement those functions and adhere to a defined pattern of what the expected return results from those function(s) should be. Drupal would then know your block existed and allow administrators to place it in a region on the page. Drupal would also know what PHP function to call to retrieve the content of your block.

The general idea is still the same in Drupal 8. Tell Drupal your block exists, and then provide PHP code that will be called when someone is trying to view or otherwise interact with your block. The mechanics however are quite a bit different.

In Drupal 8, custom blocks provided by a module implement the Block Plugin API which is a subset of the more generic Plugin API. What used to be info hooks that returned arrays for block discovery is now composed of Annotations and the use of PSR-0 so Drupal can both find and understand your blocks. Callback functions that returned the content of your block are now methods on the Drupal\block\BlockPluginInterface which you can override as needed in our custom block code.

Blocks are, of course, a really common pattern in Drupal and as such there is a helpful Drupal\block\BlockBase class that you can extend when creating your own Blocks. BlockBase provides the basic block configuration form which administrators see, access rules, and cache handling—all of which can be overridden as needed for your specific use-case. In this video I'm going to define a custom block with some very basic configuration settings and walk through:

Where you should put the code for your block
Annotation based plugin discovery and how to know what to put in the annotation
Outputting simple text in the body of a block
Changing the access rules / visibility for a block in code
Adding a custom configuration option to the block configuration form
Saving block configuration data
Using stored block configuration data
Rather than start from scratch I'll be building off the Chad module which I started in Writing a Hello World Module, and then continued to build on in Getting Started with Drupal 8 Forms and Configuration Management for Developers. The code can be found on GitHub, and you should totally grab a copy and follow along. Writing this blog post and recording this video resulted in the following documentation pages being overhauled: https://drupal.org/node/2168137 and an issue for missing documentation in core being filed: https://drupal.org/node/2248951. Now that you know how blocks work, help us get the documentation updated. :)