Drupal 8 comes with a funky new feature that allows admins and editors to customize entity forms in more than one variant. That means they can have, for different purposes, different form modes that feature different fields, with different form display configuration, etc. Nice, right?

Although you can do this in Drupal 8, not much use has yet been made of these form modes. So if you create a form mode, you cannot easily render it. Even more so, Drupal core doesn't actually make use of them.

In this article we will, however, look at how we can programatically render entity forms which use a form mode that had been created by an admin in the UI. First though, how do we render a regular entity form in Drupal 8?

Regular entity forms

$form = \Drupal::service('entity.form_builder')->getForm($entity);

$form is now a renderable array for the entity passed to the getForm() method of the EntityFormBuilder service. The entity itself can be an existing one (which will show you the edit form with values pre-filled) or a new one you just created programatically.

It's that simple.

The EntityFormBuilder::getForm() method takes a second parameter though, namely $operation. Apart from the variable name, this reminds me of how an entity itself is rendered, the second parameter to the build method being a view mode. So you'd expect in this case $operation to be a form mode, right? Well, wrong. Ish.

When an entity is defined, for example Node, under the handlers key of the annotation we have some form handlers defined. Those are what the $operation parameter expects. So for example, if we want the delete form of the Node entity, we pass delete and we get a different form. Otherwise, we fallback to the default one which is used for create/edit (although we can also specify edit but it maps to the same class anyway).

Custom form modes

Continuing with the Node example, the entity type defines three handlers (operations): default, delete, edit. That is not a lot. Other entity types can define more or less and can be differently named.

So if we create a form mode in the UI, whose machine name ends up being create_editors (for example), how do we go about rendering the entity form for nodes using that form mode? Passing that machine name as the second parameter by itself won't do the trick because the Node entity has not defined that handler, and more importantly, it doesn't map to an actual form class.

To fix this, we can alter the entity definition and add our own form handler named as our custom form mode, mapped to the default Form class of the Node entity. Here is a snippet of code, sprinkled with explanatory comments, that takes care of our Node entity for a custom form mode called create_editors:

/**
 * Implements hook_entity_type_alter().
 */
function example_module_entity_type_alter(array &$entity_types) {
  // We get all form modes, for all entities, and loop through them.
  $form_modes = \Drupal::service('entity_display.repository')->getAllFormModes();
  foreach ($form_modes as $entity_type => $display_modes) {
    if ($entity_type !== 'node') {
      // We are only interested in adding a handler to the Node entity.
      continue;
    }

    $node_type = $entity_types[$entity_type];
    foreach ($display_modes as $machine_name => $form_display) {
      if ($machine_name !== 'create_editors') {
        // We are only interested in adding this form mode to the definition.
        continue;
      }
      // We get the default handler class. It will be enough for us.
      $default_handler_class = $node_type->getHandlerClasses()['form']['default'];
      // We set the form class, keyed by the machine name of our custom form mode.
      $node_type->setFormClass($machine_name, $default_handler_class);
    }
  }
}

So basically, we are supplementing the Node form handlers with a new one called create_editors which maps to the default form class, in this case Drupal\node\NodeForm. The form class itself is not so important because after it is built, if there is a form mode with that name, it will be used to override the default form with all the configuration of that form mode. So building our node form with our custom form mode would now go like this:

$form = \Drupal::service('entity.form_builder')->getForm($entity, 'create_editors');

And that is pretty much it. Of course you can loop through all the entity types and add all form modes if you want. But I always like to inject my custom functionality only to the extent I need, touching as little as possible.

Let me know how this works for you.