Display Modes, View Modes, and Form Modes

Last updated on
15 February 2017

Display modes

Display modes (found at admin/structure/display-modes) exist to provide different presentations of Content Entities for either viewing or editing. The two types of display modes are "view modes" and "form modes." Both of these display mode types—view modes and form modes—are examples of "configuration entities." Here is an example of an exported view mode.

uuid: 15dc7aa9-13fd-4412-9c06-06d09f915d08
langcode: en
status: false
dependencies:
  module:
    - node
id: node.full
label: 'Full content'
targetEntityType: node
cache: true

reference: core.entity_view_mode.node.full.yml

The main property to take note of is the "targetEntityType" property. Each display mode (view mode or form mode) is associated with one, and only one, type of Content Entity. By convention there are labels that get used for multiple display modes. For instance, Drupal Core’s standard profile uses the word “Full” in the labels of view modes for the content entity types of node, custom blocks and comments.

View modes and view displays

  • Administered in aggregate at: /admin/structure/display-modes/view
  • Enabled per bundle under "Custom display settings" at urls like: /admin/structure/types/manage/page/display (where ‘page’ is a bundle of the node entity)
  • Configured per view mode per bundle at urls like: /admin/structure/types/manage/page/display/teaser (where ‘page’ is a bundle of the node entity and ‘teaser’ is a view mode)

View modes as a concept predate Drupal 8. They were present in Drupal 7. Drupal 6 had the concept of “build modes.” View modes exist to allow Drupal site building tools like Entity Reference fields to request a given entity be rendered in a certain way. For instance, suppose that ‘song’ and ‘artist’ are each node types and that song contains a reference field to artist. The ‘full’ display of the song node may need to render the ‘teaser’ display of the artist node. In this example ‘teaser’ is a view mode used by the artist node and ‘full’ is the view mode used by the song.

It is usually the case that if a site builder wants to display the artist node bundle in the teaser view mode then that site builder will have made configuration specific to artist and teaser. This can be done by going to the “Manage Display” tab with the entity bundle configuration page. An example of this page in the Drupal Core’s standard install profile is /admin/structure/types/manage/article/display

On this page a site builder has the option to enable customized field display settings for the bundle (field order and field formatter usage) on a per view mode basis. It is not required that all view modes have specific customizations made for all bundles. In this example, only the view modes “RSS” and “Teaser” have their own specific settings. All other view modes fall back to the “default” configuration. The association between an entity type bundle and view mode is called a View Display. @see EntityViewDisplayInterface

Screenshot of checkboxes enabling view modes for a content type

Form modes and (form) operations

  • Administered in aggregate at: /admin/structure/display-modes/form
  • Enabled per bundle at urls like: /admin/structure/types/manage/page/form-display (where ‘page’ is a bundle of the node entity)
  • Configured per form mode per bundle at URLs like: /admin/structure/types/manage/page/form-display/simple (where ‘page’ is a bundle of the node entity and ‘simple’ is a form mode).

Like view modes, form modes are a way to create different field configurations with the same content entity bundle. Form modes allow for multiple sets of field widget orderings and customizations, just as view modes allow for different orderings and customization of field formatters.

In addition to form modes, form operations allow for defining which classes should be used for forms like a node delete form. The class used to delete a node is different from the class used to edit a node. Operations are defined in an entity’s annotations.

Here is an example that will map 2 custom form operations, as well as the "default" form mode, to the same form MyEntityForm. Make sure this form extends ContentEntityForm.

/**
 * @ContentEntityType(
 *   id = "myentity",
 *   handlers = {
 *     "form" = {
 *       "default" = "Drupal\myentity\Form\MyEntityForm",
 *       "add" = "Drupal\myentity\Form\MyEntityForm",
 *       "edit" = "Drupal\myentity\Form\MyEntityForm",
 *       "delete" = "Drupal\myentity\Form\MyEntityDeleteForm",
 *     },
 *   },
 * )
 */

If you need to add or alter available form operations in existing entities you can use hook_entity_type_build and hook_entity_type_alter .

Currently there must be an explicit setting of an operation for a form mode to be used. Unlike view modes (which fall back to the default view display if view display does not exist for a given view mode) form modes will not use the ‘default’ operation by default. This could be considered a bug. See #2511720: Allow form modes to use default operation if a form operation is not explicitly set.

To display a form with a custom form mode, use _entity_form in your route. For example, to display the custom "edit" form of the MyEntity, use this route:


entity.myentity.edit_form:
 path: '/myentity/{myentity}/edit'
 defaults:
   _entity_form: myentity.edit
   _title: 'Edit MyEntity'
 requirements:
   _permission: 'edit myentity entities'