How to extend an existing Drupal 8+ Form

The Drupal FOSS CMS (Free and Open Source Software Content Management System) is considered to be the one of the most developer friendly CMS available. However, for those new to Drupal, something as "simple" as changing the text displayed after submitting a form can be daunting. Originally released in 2011, with Drupal 7, the Drupal Entity API defines different types of information stored and displayed in Drupal. When Drupal 8 was released, the concept was further refined into what's referred to as "specifically typed objects", meaning that each Entity is defined as having a specific set of information and operations that can be performed on it. As you might imagine, Drupal 8 Forms are used to perform operations on Entities, such as add, edit, and delete. When creating a form, a form handler is used to define which class should be used. So, when you want to modify the implementation of a form, you will need to extend the original form's class and tell the system to use your custom class. Simple, right? Let's step through the process...

The Use Case

In order to best illustrate the process of extending and existing Drupal 8 Form, we will modify the submit messages for the Simplenews subscribe form.

Setup Your Dev Environment

When creating new functionality for your Drupal website, it is always best to use a local development environment. We recommend using Docksal with Docker to accomplish this task because it is simple to setup and includes essential tools for developing with Drupal. We are also going to make sure the contrib module we are modifying is installed and enabled.

1. Goto Docksal.io and follow install instructions for your Operating System on the OS Support tab to install Docksal with Docker
2. Open Terminal/Console
3. Create projects directory: mkdir ~/Sites
4. Create project with Docksal: fin project create
5. Name your project & Choose Drupal 8 when prompted (Composer Version is recommended)
   
   extendform
6. Enter y to proceed with setup
   
7. Verify you able to access the website using the URL and credentials provided when the install is complete
   
8. Change to your project's directory: cd ~/Sites/{project_name}
   
9. If the original form is provided by a contributed module, install it: fin composer require 'drupal/{contrib_project}:^{version}'
   

and enable it: fin drush en {contrib_project}

Generate Your Custom Module

Now that your local environment is setup, you will need to generate your custom module that will provide the code that will extend the existing form you are modifying. We recommend using Drupal Console to accomplish this task. No need to install Drupal Console because it comes pre-installed with Docksal!

1. Generate Module: fin drupal generate:module
   NOTE: Do not generate a composer.json file now because it will produce an error
   

and Enter/yes when prompted

2. Generate Composer File: fin drupal generate:composer
   

and Enter/yes when prompted

Locate the Existing Form Code

In this scenario, we are wanting to change the message that displays after subscribing to a newsletter provided by the Simplenews module. Let's look for the original code that generates that message.

1. Search Files for message: grep -rl "{message}" .
   
2. Open Project in your favorite file editor. Ex: bbedit .
   Navigate to file from search in Step 1
   
3. Locate message in file to verify function that needs to be customized. CTRL(Win)/Command(Mac)+F
   

Copy and Rename the Form File

The easiest way to limit the number of mistakes is to copy the existing files from the original location into your custom module.

1. Prepare Destination Folder: mkdir -p web/modules/custom/{custom_module}/src/Form
   
2. Copy Files: cp web/modules/contrib/simplenews/src/Form/SubscriptionsBlockForm.php web/modules/custom/{custom_module}/src/Form/
   
3. Rename Files (so unique): mv web/modules/custom/customize_simplenews_sub_form/src/Form/SubscriptionsBlockForm.php web/modules/custom/{custom_module}/src/Form/SubscriptionsCustomBlockForm.php
   
4. Repeat Steps 2 & 3 for all applicable files in Step 1. NOTE: In this scenario, we did not need to change the file in the Tests directory.

Customize the Form Code

Now we need to modify the Code so that it extends the existing code.

1. Alter namespace to your Custom module: namespace Drupal\{custom_module}\Form;
   
2. Add use statement for original code with alias that is same as what was extended in Original Code: use Drupal\simplenews\Form\SubscriptionsBlockForm as SubscriptionsFormBase;
   
3. Customize Class name to make unique for your module: SubscriptionsCustomBlockForm
   
4. Remove all code in file, except function located in Step 4 of the Locate the Existing Form Code: getSubmitMessage()
   Before editing code:
   
   After removing extra code:
   
5. Alter code, as needed. Ex: line 19: return $this->t('This is a different update message.');
   

Set the Form Handler Class

Almost done coding! Just need to edit the Handler Class for the entity we are modifying.

1. Add hook to alter entity: function customize_simplenews_sub_form_entity_type_alter(array &$entity_types)
2. Edit handler class for entity: @var $entity_types \Drupal\Core\Entity\EntityTypeInterface[]
   

Enable Your Custom Module

Congrats! The coding is over! Now, just enable the module, refresh and test to verify.

1. Verify system sees module: fin drush pml | grep {custom_module}
   
2. Enable the Custom Module: fin drush en {custom_module}
   
3. If warning encountered during enable:
   [warning] Invalid json in modules/custom/customize_simplenews_sub_form/composer.json
   a. Disable the Custom Module: fin drush pmu {custom_module}
   
   b. Open the custom modules composer.json file: bbedit ~/Sites/{custom_module}/composer.json
   
   c. Remove extra comma in require section & Save changes.
   
   d. Enable the Custom Module: fin drush en {custom_module}
   
4. Revisit Subscription Page Verify Changes. NOTE: If this is a fresh install, you may need to add the simplenews block to the sidebar.

Congrats!

You have successfully extended and existing form programmatically the "Drupal way". Hopefully, this introduction to extending Drupal code has provided you with a simple use case that will help you to continue extending other code. If you ever get stuck, please don't hesitate to contact me to sign-up for a mentoring session.