Block configuration

Before we close the book on our custom block plugin, 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 could achieve this with three to four methods on our plugin class.

First, we would need to implement the defaultConfiguration() method, in which we describe the items of configuration that we are storing for this block and the default values for these items. So, we could 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 use the number 1 as the value to a fictitious key named enabled.

Next, we would 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;
}

With the appropriate extra 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 handy getConfiguration() method
 of the parent class to load up the configuration values that get saved with this block. If none have been saved, note that the enabled key will be present in it with the default value we set above (1).

Lastly, we would 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:

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

It couldn't be simpler than this. Now if we placed our custom block somewhere, the form we are presented with would incorporate our form element that allows us to toggle the enabled key. What remains to be done is to make use of this value inside the build() method. We could 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. The method name is blockValidate(), has the same signature as blockSubmit() and works the same way as the validation handler we saw when we built our standalone form. So, I won't repeat that here.