field ui

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

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

Help out with Field API for Drupal 8

Last week, I attended the Field API pre Drupalcon sprint in Munich. My major motivation was to start working on the conversion of Field API to CMI and little than a week later, we have a patch that is green. While there's still a lot of work on it, it's still a good feeling after one week of hacking and discussions. After driving 8 hours home after a fantastic week, I decided to step up as a co-maintainer of Field API. But me stepping up won't make the big difference, we need more people joining us!

Anyone can help in many different ways

  • Gardening the queue: go through bug reports, ask for more info when something is not clear or close duplicates.
  • You can work on an issue by creating patches. Assign an issue to yourself so we know who's working on it.
  • Help by reviewing and testing patches to see if they actually work as intented.
  • Come bring us coffee and cake :)

Where should I start ?

There's a lot of work, that's for sure: CMI, widget and formatter plugins, Field API vs OO and so on. We have a site which lists the most important issues: http://realize.be/field-api - Bookmark that if you're interested!

We are also available on freenode.net on #drupal-fieldapi in case you have any questions.

How much time should I invest in this ?

That is totally up to you. Remember, this is voluntary work, so we do not expect anybody to work 40 hours a week - although that would be more than fantastic of course :) As an example, this is roughly what I think my weekly schedule will look like:

  1. Continue working further on the CMI patch. I have sponsored time from Wunderkraut so I can focus hard on getting this critical piece of functionality in. Goodbye field_config and field_config_instance tables!
  2. Go through the queue twice a week for about an hour and review existing patches from other people.
  3. Go through the queue twice a week for half an hour and close duplicates or ask for more info.
  4. Pick one 'quick win' issue per week to create a patch from it, either a bug or feature request.
  5. Work on Display Suite issue queue, this usually happens once a week for about 3 hours. Been like that since forever.

So wait, I thought you didn't sleep?

Yes I do, and I do other things as well. It's not worth spending all your nights on coding, you'll get burned out before you know it. But wouldn't it be great to go to sleep and someone else was doing some great work ?

So, who's helping along?

Managing any form with Renderable elements, Field group and Display suite

Little than a week ago, I committed Renderable elements which enables you to register any piece of build in your Drupal 7 installation and manage that through Field UI. It will make additional fields available of existing entities on the manage forms/display screens or you can for example register the contact form, webform or (let's go crazy) the exposed filter form of a view and rearrange the fields with Field UI. Essentialy, the idea is that you can rip out all elements which are nested, also those inside the vertical tab on the node edit form for instance.

How it works

Currently, only forms are supported, support for any kind of other non entity display is coming soon. Once you enable the module, you can go to admin/config/system/rel/config and enable the registration link on top of forms. Now go to any form in your installation and you'll see a 'Manage form display' link on top. Clicking on the link will make the form available to manage. An overview can be found at admin/config/system/rel. In case you're registering a non entity form, this build will be inserted as a bundle into a new entity that's exposed by the module. This way, we can profit from hook_field_extra_fields to register any kind of element. Tricky ? Sure. Cool, oh yeah!

Any kind of custom registration is exportable thanks to CTools as well.

The power

The idea from the module came after the initial proof of concepts while working on forms support for Display suite. Soon after, an issue appeared as well in the Field group issue queue to make field groups available in other contexts than entities and the ability to rip out the elements that are nested inside vertical tabs. Of course, anything can be done with form alter, but our goal was to make this possible through Field UI. Now, we don't want to force people Field group and/or DS, so we decided to create a separate project, which also means there are no dependencies. If offers a lot benefits and the possibilities you have now are huge:

  1. Install this as a stand alone module and it will make any element on the form available like the Save/Preview/Delete button, vertical tabs etc.
  2. Install Field group and you can take control of existing field groups or add new ones on say the contact form.
  3. Install Display suite and you can now select a template file to manage the layout of registered forms, like webform etc.

Both modules (rel and ds_forms) still need cleanup, but also a lot of testing, so please test as much edge cases as you can and report back into the issue queue!

This might all seem a bit cryptic, so, we've recorded a screencast showing you the power of Renderable elements together with Field group and Display suite on node, contact, webform and views exposed filter forms.

Subscribe to RSS - field ui

You are here