File formatters need to manually check the 'display' property of each item

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:

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:

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;
  }
}