Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

File field values have a 'display' property (presented as a "Display" checkbox in the file widget) that allows files to be uploaded and added to the file system without being listed in the parent entity.

In Drupal 7, the "prepare view" step for file fields, file_field_prepare_view(), handled that property by removing the corresponding values from the entity, thus allowing formatters to simply iterate on the items they received and display them. Modifying the values from the entity itself, however, is not a good practice and can have nasty consequences (e.g. values purely disappearing from storage if the entity is saved after having been displayed).

in Drupal 8, the values with 'display' == FALSE are not removed anymore, and each formatter needs to take care of checking the 'display' property on each item before rendering it. The \Drupal\file\Plugin\field\formatter\FileFormatterBase base class provides an isDisplayed($item) method to make that easier.

Code examples:

Drupal 7:

<?php
function mymodule_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
 
$element = array();
  foreach (
$items as $delta => $item) {
    if (isset(
$item['entity']) {
     
$element[$delta] = ... the render array for $item...
    }
  }
  return
$element;
}
?>

Drupal 8:

<?php
class MyFileFormatter extends FileFormatterBase {

 
// ...

 
public function viewElements(FieldItemListInterface $items) {
   
$elements = array();
    foreach (
$items as $delta => $item) {
      if (
$this->isDisplayed($item) && $item->entity) {
       
$elements[$delta] = ... the render array for $item...
      }
    }
    return
$elements;
  }
}
?>
Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done