Drupal 8 Field API series part 4: entity (form) displays and display modes

Written on December 2, 2013 - 10:14

This is part 4 of the Drupal 8 Field API series. We skipped part 3 about field types as the dust hasn't settled yet in terms of API changes. Once we get there, we'll make sure we'll talk about the massive changes that have happened in that area.

In this part, we'll talk about new API's which are, strictly speaking, not part anymore of Field API, they now belong to the Entity Field API. However, the reason the changes exist, directly comes out of a big problem in Drupal 7 in Field API: scattered storage.

Entity display

In Drupal 7, parameters controlling how to render the various "parts" of an entity view in a given view mode were scattered in many separate locations:

in $instance['display'] for each individual (Field API) field in the bundle
in the 'field_bundle_settings_[entity_type]_[bundle]' variable for the 'extra fields' in the bundle
in other places for contrib additions that are not one of the two above (most notably field_group module)

In Drupal 8, all those parameters ("options") for all those parts ("components") are centralised in one single EntityViewDisplay configuration object - which means they can be deployed with CMI - for each entity bundle and view mode. You can access these objects with the entity_get_display() function. All available methods can be found in EntityDisplayInterface.

<?php entity_get_display('node', 'article', 'default')   // Set 'component_1' to be visible, with weight 1.   ->setComponent('component_1', array(     'weight' => 1,   ))   // Set 'component_2' to be hidden.   ->removeComponent('component_2')   ->save(); ?>

Also new in D8 is that all entity and field rendering hooks now receive this EntityDisplay object as a parameter. This means you have direct access to the configuration in your functions, instead of having to figure them out by calling functions to get the definition of field instances, extra fields or other configurations. For the full list of all hooks affected, scroll to the resources part at then end of this article for the change record link.

<?php function hook_node_view(Node $node, EntityDisplay $display, $view_mode, $langcode) {   if ($display->getComponent('mymodule_addition')) {     $node->content['mymodule_addition'] = array(       '#markup' => mymodule_addition($node),       '#theme' => 'mymodule_my_additional_field',     );   } } ?>

Note that currently only Field API fields and extra fields are handled by the EntityViewDisplay object. This is going to change when we introduce component type plugins so everyone will be able to store and access configuration. For more information, follow https://drupal.org/node/1875974.

Entity form display

Just like with the display settings, form settings are scattered all over the place:

in $instance['widget'] for each individual (Field API) field in the bundle
in the 'field_bundle_settings_[entity_type]_[bundle]' variable for the 'extra fields' in the bundle
in other places for contrib additions that are not one of the two above (most notably field_group module)

In Drupal 8, all those parameters ("options") for all those parts ("components") are centralised in one single EntityFormDisplay configuration object for each entity bundle and form mode.This object uses the same EntityDisplayInterface as the EntityViewDisplay object. The consequence of this API is the birth of the counterpart of view modes: form modes.

The direct use case for this was the hacky workaround in Drupal 7 for showing Field API fields on the user registration page. In Drupal 8, you can now configure which fields are available on the user registration page or the edit page. However, more interesting possibilities with this new API will certainly pop up when Drupal 8 is released, most notable inline entity forms.

UI impact

In Drupal 7, the place to manage the fields and control the order in forms is done on the 'manage fields' screen. In Drupal 8, this has has been split out in the 'manage fields' and the 'manage form display' screens. Widget settings are now also managed on this new screen, which allows you to have different widget settings depending on the form mode. The form displays screen also have a 'hidden' region, which allows you to hide certain fields on certain form modes.

Display modes

Drupal 7 has the concept of 'view modes', previously build modes in D6. In D8, we now also have form modes and both of them are configuration entities. Drupal 8 also ships with a UI to manage these display modes. You do not have to rely anymore on contributed modules like 'View modes' or 'Display Suite'.

Resources

Change record: Introduced EntityDisplay config entities.
Change record: Introduced EntityFormDisplay config object.
Change record: Entity & field rendering hooks receive an additional EntityDisplay parameter.
Change record: View Modes are stored in the config system.
Change record: field_bundle_settings() has been removed.
Change record: field_behaviors_widget() is removed

Original Article:

Drupal 8 Field API series part 4: entity (form) displays and display modes