Block configuration

Before we close the book on our custom block plugin, though, let's take a look at how we can add a configuration form to it. This way, we can practice using some more Form API elements and see how we can store and use block configuration.

Even though our functionality is complete (for the moment), let's imagine that we need a Boolean-like control on our block configuration so that when an admin places the block, they can toggle something and that value can be used in the build() method. We can achieve this with three to four methods on our plugin class.

First, we will need to implement the defaultConfiguration() method, in which we can describe the items of configuration that we are storing for this block and the default values of these items. So, we can have something like this:

  /**
   * {@inheritdoc}
   */
  public function defaultConfiguration() {
    return [
      'enabled' => 1,
    ];
  }

We return an array of keys and values that will be in the configuration. Also, since we said we are going with a Boolean field, we'll use the number 1 as the value to a fictitious key, enabled.

Next, we will need to implement the blockForm() method, which provides our form definition for this configuration item:

  /**
   * {@inheritdoc}
   */
  public function blockForm($form, FormStateInterface $form_state) {
    $config = $this->getConfiguration();

    $form['enabled'] = array(
      '#type' => 'checkbox',
      '#title' => t('Enabled'),
      '#description' => t('Check this box if you want to enable this feature.'),
      '#default_value' => $config['enabled'],
    );

    return $form;
  }

Let's not forget the use statement at the top of the file:

use Drupal\Core\Form\FormStateInterface;

As you can see, this is a typical Form API definition for one form element of the type checkbox. Additionally, we are using the getConfiguration() handy method of the parent class to load up the configuration values that get saved with this block. If none have been saved, you'll note that the enabled key will be present in it with the default value we set above (1).

Lastly, we will need the submit handler that will do the necessaries to store the configuration. I used inverted commas because we don't actually have to do anything related to storage, but just map the value submitted in the form to the relevant key in the configuration. The block system does it for us. Also, no extra processing is needed, in our case, either:

  /**
   * {@inheritdoc}
   */
  public function blockSubmit($form, FormStateInterface $form_state) {
    $this->configuration['enabled'] = $form_state->getValue('enabled');
  }

It couldn't be simpler than this. Now when we place our custom block somewhere, the form we are presented with will incorporate our form elements that allow us to toggle the enabled key. What remains to be done is to make use of this value inside the build() method. We can do that similarly to how we loaded the configuration values inside the buildForm() method:

$config = $this->getConfiguration();

Alas, we don't really need this configuration in our example block, so we won't be adding it to our code. However, it is important for you to know how to do it, so we covered it here. Moreover, before moving on, I also want to specify that you can use an optional method to handle validation on the configuration form, that is, blockValidate(), which will take the same parameters as blockSubmit() and will work the same way as the validation handler we saw when we built our standalone form. So, I won't repeat that here.