Using Drupal 8 Entity Form Displays

In Drupal 7 we had view modes, where we could specify different views for an entity and show different fields within each view. Drupal 8 now extends this further and allows form display modes. These are incredibly useful, as they can be used to easily create multipart entity forms. For this example I’ll show you how you can split up a user registration form into multiple forms using the display modes.

First of all, I’m going to add some custom fields to the user entity. You will need to login to the admin area, go to Configuration > People > Account Settings.

Next I am going to create two new form modes, one for the new registration form and one for the additional details form. Go to Structure > Display Modes > Form Modes and click on Add new form mode. Click on the User entity type and name your form mode. I am going to name mine ‘Simple Registration’ and ‘Additional Details’ and Drupal gives this these the machine names simple_registration and additional_details.

Now I’m going to go back to the Account settings configuration page and click on the Manage form display tab. At the bottom of the page, you’ll see a section called custom display settings. Click on the box to expand it and you will see the register display mode and the new ones just added, additional details and simple register. The register form mode is the default registration form mode, I am not editing this for this tutorial as this will also edit the admin add new user form, so it’s cleaner to add a whole new form and separate these. Select the new form modes and press save.

Now at the top of the page, you will see the form modes appear as tabs. You can click on a form mode and specify which fields will appear for that mode. For the Simple Register form mode I will only show the username and password.

From the Additional Details form mode I will show the Picture, First Name and Last Name.

Now that we have specified the form modes, we need to add in the forms. First of all we’ll need to create a new module. I use Drupal Console to quickly create the boilerplate code for this. For the new registration form, I am going to extend the existing RegisterForm class. This already has all the checks built in for a new user and I am just going to change the save method to login the user and redirect to the second part of the form.

The final part of this form redirects to a route that we have not yet created. This will be the route name for the additional details form. To create this form, I will create a basic content entity form, extending the Drupal\Core\Entity\ContentEntityForm class. I am setting the field_first_name and field_last_name fields to required within the build method. This is because if you set a field to required within the entity field settings itself, it will mean that it will always be required on all form displays the field is included in. Adding it within this form class means they’ll only be required on this form.

The next step is to register these entity forms to the user entity. If creating forms for an entity that is within your module, you can add the forms to the entity class itself, within the annotations. Here is a section from the core User entity (core/modules/user/src/Entity/User.php).

*     "form" = {
*       "default" = "Drupal\user\ProfileForm",
*       "cancel" = "Drupal\user\Form\UserCancelForm",
*       "register" = "Drupal\user\RegisterForm"
*     },

As we are adding these forms to the core user entity, we will need to do this from within hook_entity_type_build. The name of the entity form should match the machine name for the form modes created earlier.

We now have form modes setup with their corresponding entity forms. The final step is to add in the routes so that we can get to the new registration forms. You will need to create a routing.yml file within your module.

Now, when we enable the module we will be able to go to the new registration page (/register) and only the username and password fields show as defined in the form mode (the password will not appear if email verification is turned on).

When valid details are entered and the create new account button is clicked, it then logs the user in and redirects them to the additional details form. The fields from the additional_details form mode are shown on this form.

Now that the forms are in place, fields can be moved about within form modes and these changes will be reflected in the forms without the need to modify any code.