Issue #2677990 by DuaelFr, agomezmoron, heykarthikwithu, gvso, alexpott, Wim Leers, larowlan: Add a setting on "Table of files" and "Generic files" formatters to use files descriptions (or not)

core/modules/field/tests/src/Kernel/Migrate/d6/MigrateFieldFormatterSettingsTest.php

@@ -129,11 +129,14 @@ class MigrateFieldFormatterSettingsTest extends MigrateDrupal6TestBase {
     // Test the file field formatter settings.
     $expected['weight'] = 8;
     $expected['type'] = 'file_default';
-    $expected['settings'] = [];
+    $expected['settings'] = [
+      'use_description_as_link_text' => TRUE
+    ];
     $component = $display->getComponent('field_test_filefield');
     $this->assertIdentical($expected, $component);
     $display = EntityViewDisplay::load('node.story.default');
     $expected['type'] = 'file_url_plain';
+    $expected['settings'] = [];
     $component = $display->getComponent('field_test_filefield');
     $this->assertIdentical($expected, $component);
 

core/modules/file/config/schema/file.schema.yml

@@ -73,13 +73,17 @@ field.field_settings.file:
 field.formatter.settings.file_default:
   type: mapping
   label: 'Generic file format settings'
+  mapping:
+    use_description_as_link_text:
+      type: boolean
+      label: 'Replace the file name by its description when available'
 
 field.formatter.settings.file_rss_enclosure:
   type: mapping
   label: 'RSS enclosure format settings'
 
 field.formatter.settings.file_table:
-  type: mapping
+  type: field.formatter.settings.file_default
   label: 'Table of files format settings'
 
 field.formatter.settings.file_url_plain:

core/modules/file/file.install

@@ -5,6 +5,8 @@
  * Install, update and uninstall functions for File module.
  */
 
+use Drupal\Core\Entity\Entity\EntityViewDisplay;
+
 /**
  * Implements hook_schema().
  */
@@ -128,3 +130,37 @@ function file_update_8300() {
 
   return t('Files that have no remaining usages are no longer deleted by default.');
 }
+
+/**
+ * Add 'use_description_as_link_text' setting to file field formatters.
+ */
+function file_update_8001() {
+  $displays = EntityViewDisplay::loadMultiple();
+  foreach ($displays as $display) {
+    /** @var \Drupal\Core\Entity\Entity\EntityViewDisplay $display */
+    $fields_settings = $display->get('content');
+    $changed = FALSE;
+    foreach ($fields_settings as $field_name => $settings) {
+      if (!empty($settings['type'])) {
+        switch ($settings['type']) {
+          // The file_table formatter never displayed available descriptions
+          // before, so we disable this option to ensure backward compatibility.
+          case 'file_table':
+            $fields_settings[$field_name]['settings']['use_description_as_link_text'] = FALSE;
+            $changed = TRUE;
+            break;
+
+          // The file_default formatter always displayed available descriptions
+          // before, so we enable this option to ensure backward compatibility.
+          case 'file_default':
+            $fields_settings[$field_name]['settings']['use_description_as_link_text'] = TRUE;
+            $changed = TRUE;
+            break;
+        }
+      }
+    }
+    if ($changed === TRUE) {
+      $display->set('content', $fields_settings)->save();
+    }
+  }
+}

core/modules/file/src/Plugin/Field/FieldFormatter/DescriptionAwareFileFormatterBase.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace Drupal\file\Plugin\Field\FieldFormatter;
+
+use Drupal\Core\Form\FormStateInterface;
+
+/**
+ * Base class for file formatters that have to deal with file descriptions.
+ */
+abstract class DescriptionAwareFileFormatterBase extends FileFormatterBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function defaultSettings() {
+    $settings = parent::defaultSettings();
+
+    $settings['use_description_as_link_text'] = TRUE;
+
+    return $settings;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function settingsForm(array $form, FormStateInterface $form_state) {
+    $form = parent::settingsForm($form, $form_state);
+
+    $form['use_description_as_link_text'] = [
+      '#title' => $this->t('Use description as link text'),
+      '#description' => $this->t('Replace the file name by its description when available'),
+      '#type' => 'checkbox',
+      '#default_value' => $this->getSetting('use_description_as_link_text'),
+    ];
+
+    return $form;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function settingsSummary() {
+    $summary = parent::settingsSummary();
+
+    if ($this->getSetting('use_description_as_link_text')) {
+      $summary[] = $this->t('Use description as link text');
+    }
+
+    return $summary;
+  }
+
+}

core/modules/file/src/Plugin/Field/FieldFormatter/GenericFileFormatter.php

@@ -15,7 +15,7 @@ use Drupal\Core\Field\FieldItemListInterface;
  *   }
  * )
  */
-class GenericFileFormatter extends FileFormatterBase {
+class GenericFileFormatter extends DescriptionAwareFileFormatterBase {
 
   /**
    * {@inheritdoc}
@@ -28,7 +28,7 @@ class GenericFileFormatter extends FileFormatterBase {
       $elements[$delta] = [
         '#theme' => 'file_link',
         '#file' => $file,
-        '#description' => $item->description,
+        '#description' => $this->getSetting('use_description_as_link_text') ? $item->description : NULL,
         '#cache' => [
           'tags' => $file->getCacheTags(),
         ],

core/modules/file/src/Plugin/Field/FieldFormatter/TableFormatter.php

@@ -15,7 +15,7 @@ use Drupal\Core\Field\FieldItemListInterface;
  *   }
  * )
  */
-class TableFormatter extends FileFormatterBase {
+class TableFormatter extends DescriptionAwareFileFormatterBase {
 
   /**
    * {@inheritdoc}
@@ -27,11 +27,13 @@ class TableFormatter extends FileFormatterBase {
       $header = [t('Attachment'), t('Size')];
       $rows = [];
       foreach ($files as $delta => $file) {
+        $item = $file->_referringItem;
         $rows[] = [
           [
             'data' => [
               '#theme' => 'file_link',
               '#file' => $file,
+              '#description' => $this->getSetting('use_description_as_link_text') ? $item->description : NULL,
               '#cache' => [
                 'tags' => $file->getCacheTags(),
               ],

core/modules/file/src/Tests/FileFieldDisplayTest.php

@@ -4,6 +4,7 @@ namespace Drupal\file\Tests;
 
 use Drupal\Core\Field\FieldStorageDefinitionInterface;
 use Drupal\file\Entity\File;
+use Drupal\node\Entity\Node;
 
 /**
  * Tests the display of file fields in node and views.
@@ -173,4 +174,49 @@ class FileFieldDisplayTest extends FileFieldTestBase {
     $this->assertText(t('The description may be used as the label of the link to the file.'));
   }
 
+  /**
+   * Tests description display of File Field.
+   */
+  public function testDescriptionDefaultFileFieldDisplay() {
+    $field_name = strtolower($this->randomMachineName());
+    $type_name = 'article';
+    $field_storage_settings = [
+      'display_field' => '1',
+      'display_default' => '1',
+      'cardinality' => FieldStorageDefinitionInterface::CARDINALITY_UNLIMITED,
+    ];
+    $field_settings = [
+      'description_field' => '1',
+    ];
+    $widget_settings = [];
+    $this->createFileField($field_name, 'node', $type_name, $field_storage_settings, $field_settings, $widget_settings);
+
+    $test_file = $this->getTestFile('text');
+
+    // Create a new node with the uploaded file.
+    $nid = $this->uploadNodeFile($test_file, $field_name, $type_name);
+
+    // Add file description.
+    $description = 'This is the test file description';
+    $this->drupalPostForm("node/$nid/edit", [$field_name . '[0][description]' => $description], t('Save'));
+
+    // Load uncached node.
+    \Drupal::entityTypeManager()->getStorage('node')->resetCache([$nid]);
+    $node = Node::load($nid);
+
+    // Test default formatter.
+    $this->drupalGet('node/' . $nid);
+    $this->assertFieldByXPath('//a[@href="' . $node->{$field_name}->entity->url() . '"]', $description);
+
+    // Change formatter to "Table of files".
+    $display = \Drupal::entityTypeManager()->getStorage('entity_view_display')->load('node.' . $type_name . '.default');
+    $display->setComponent($field_name, [
+      'label' => 'hidden',
+      'type' => 'file_table',
+    ])->save();
+
+    $this->drupalGet('node/' . $nid);
+    $this->assertFieldByXPath('//a[@href="' . $node->{$field_name}->entity->url() . '"]', $description);
+  }
+
 }

core/modules/file/src/Tests/Update/FileUpdateTest.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Drupal\file\Tests\Update;
+
+use Drupal\system\Tests\Update\UpdatePathTestBase;
+
+/**
+ * Tests File update path.
+ *
+ * @group file
+ */
+class FileUpdateTest extends UpdatePathTestBase {
+
+  /**
+   * Modules to enable after the database is loaded.
+   */
+  protected static $modules = ['file'];
+
+  /**
+   * {@inheritdoc}
+   */
+  protected function setDatabaseDumpFiles() {
+    $this->databaseDumpFiles = [
+      __DIR__ . '/../../../../system/tests/fixtures/update/drupal-8.bare.standard.php.gz',
+      __DIR__ . '/../../../tests/fixtures/update/drupal-8.file_formatters_update_2677990.php',
+    ];
+  }
+
+  /**
+   * Tests file_update_8001().
+   */
+  public function testPostUpdate8001() {
+    $view = 'core.entity_view_display.node.article.default';
+
+    // Check that field_file_generic formatter has no
+    // use_description_as_link_text setting.
+    $formatter_settings = $this->config($view)->get('content.field_file_generic_2677990.settings');
+    $this->assertTrue(!isset($formatter_settings['use_description_as_link_text']));
+
+    // Check that field_file_table formatter has no use_description_as_link_text
+    // setting.
+    $formatter_settings = $this->config($view)->get('content.field_file_table_2677990.settings');
+    $this->assertTrue(!isset($formatter_settings['use_description_as_link_text']));
+
+    // Run updates.
+    $this->runUpdates();
+
+    // Check that field_file_generic formatter has a
+    // use_description_as_link_text setting which value is TRUE.
+    $formatter_settings = $this->config($view)->get('content.field_file_generic_2677990.settings');
+    $this->assertEqual($formatter_settings, ['use_description_as_link_text' => TRUE]);
+
+    // Check that field_file_table formatter has a use_description_as_link_text
+    // setting which value is FALSE.
+    $formatter_settings = $this->config($view)->get('content.field_file_table_2677990.settings');
+    $this->assertEqual($formatter_settings, ['use_description_as_link_text' => FALSE]);
+  }
+
+}

core/modules/file/tests/fixtures/update/core.entity_view_display.node.article.default_2677990.yml

@@ -0,0 +1,71 @@
+uuid: 9ca49b35-b49d-4014-9337-965cdf15b61e
+langcode: en
+status: true
+dependencies:
+  config:
+    - field.field.node.article.body
+    - field.field.node.article.comment
+    - field.field.node.article.field_file_generic_2677990
+    - field.field.node.article.field_file_table_2677990
+    - field.field.node.article.field_image
+    - field.field.node.article.field_tags
+    - image.style.large
+    - node.type.article
+  module:
+    - comment
+    - file
+    - image
+    - text
+    - user
+_core:
+  default_config_hash: JtAg_-waIt1quMtdDtHIaXJMxvTuSmxW7bWyO6Zd68E
+id: node.article.default
+targetEntityType: node
+bundle: article
+mode: default
+content:
+  body:
+    type: text_default
+    weight: 0
+    settings: {  }
+    third_party_settings: {  }
+    label: hidden
+  comment:
+    label: above
+    type: comment_default
+    weight: 20
+    settings:
+      pager_id: 0
+    third_party_settings: {  }
+  field_file_generic_2677990:
+    weight: 101
+    label: above
+    settings: {  }
+    third_party_settings: {  }
+    type: file_default
+  field_file_table_2677990:
+    weight: 102
+    label: above
+    settings: {  }
+    third_party_settings: {  }
+    type: file_table
+  field_image:
+    type: image
+    weight: -1
+    settings:
+      image_style: large
+      image_link: ''
+    third_party_settings: {  }
+    label: hidden
+  field_tags:
+    type: entity_reference_label
+    weight: 10
+    label: above
+    settings:
+      link: true
+    third_party_settings: {  }
+  links:
+    weight: 100
+    settings: {  }
+    third_party_settings: {  }
+hidden: {  }

core/modules/file/tests/fixtures/update/drupal-8.file_formatters_update_2677990.php

@@ -0,0 +1,88 @@
+<?php
+
+/**
+ * @file
+ * Contains database additions to drupal-8.bare.standard.php.gz for testing the
+ * upgrade path of https://www.drupal.org/node/2677990.
+ */
+
+use Drupal\Core\Database\Database;
+use Drupal\Component\Serialization\Yaml;
+use Drupal\field\Entity\FieldStorageConfig;
+
+$connection = Database::getConnection();
+
+// Configuration for a file field storage for generic display.
+$field_file_generic_2677990 = Yaml::decode(file_get_contents(__DIR__ . '/field.storage.node.field_file_generic_2677990.yml'));
+
+// Configuration for a file field storage for table display.
+$field_file_table_2677990 = Yaml::decode(file_get_contents(__DIR__ . '/field.storage.node.field_file_table_2677990.yml'));
+
+$connection->insert('config')
+  ->fields([
+    'collection',
+    'name',
+    'data',
+  ])
+  ->values([
+    'collection' => '',
+    'name' => 'field.storage.' . $field_file_generic_2677990['id'],
+    'data' => serialize($field_file_generic_2677990),
+  ])
+  ->values([
+    'collection' => '',
+    'name' => 'field.storage.' . $field_file_table_2677990['id'],
+    'data' => serialize($field_file_table_2677990),
+  ])
+  ->execute();
+// We need to Update the registry of "last installed" field definitions.
+$installed = $connection->select('key_value')
+  ->fields('key_value', ['value'])
+  ->condition('collection', 'entity.definitions.installed')
+  ->condition('name', 'node.field_storage_definitions')
+  ->execute()
+  ->fetchField();
+$installed = unserialize($installed);
+$installed['field_file_generic_2677990'] = new FieldStorageConfig($field_file_generic_2677990);
+$installed['field_file_table_2677990'] = new FieldStorageConfig($field_file_table_2677990);
+$connection->update('key_value')
+  ->condition('collection', 'entity.definitions.installed')
+  ->condition('name', 'node.field_storage_definitions')
+  ->fields([
+    'value' => serialize($installed)
+  ])
+  ->execute();
+
+// Configuration for a file field storage for generic display.
+$field_file_generic_2677990 = Yaml::decode(file_get_contents(__DIR__ . '/field.field.node.article.field_file_generic_2677990.yml'));
+
+// Configuration for a file field storage for table display.
+$field_file_table_2677990 = Yaml::decode(file_get_contents(__DIR__ . '/field.field.node.article.field_file_table_2677990.yml'));
+
+$connection->insert('config')
+  ->fields([
+    'collection',
+    'name',
+    'data',
+  ])
+  ->values([
+    'collection' => '',
+    'name' => 'field.field.' . $field_file_generic_2677990['id'],
+    'data' => serialize($field_file_generic_2677990),
+  ])
+  ->values([
+    'collection' => '',
+    'name' => 'field.field.' . $field_file_table_2677990['id'],
+    'data' => serialize($field_file_table_2677990),
+  ])
+  ->execute();
+
+// Configuration of the view mode to set the proper formatters.
+$view_mode_2677990 = Yaml::decode(file_get_contents(__DIR__ . '/core.entity_view_display.node.article.default_2677990.yml'));
+
+$connection->update('config')
+  ->fields([
+    'data' => serialize($view_mode_2677990),
+  ])
+  ->condition('name', 'core.entity_view_display.' . $view_mode_2677990['id'])
+  ->execute();

core/modules/file/tests/fixtures/update/field.field.node.article.field_file_generic_2677990.yml

@@ -0,0 +1,27 @@
+uuid: d352a831-c267-4ecc-9b4e-7ae1896b2241
+langcode: en
+status: true
+dependencies:
+  config:
+    - field.storage.node.field_file_generic_2677990
+    - node.type.article
+  module:
+    - file
+id: node.article.field_file_generic_2677990
+field_name: field_file_generic_2677990
+entity_type: node
+bundle: article
+label: 'File generic'
+description: ''
+required: false
+translatable: false
+default_value: {  }
+default_value_callback: ''
+settings:
+  file_directory: '[date:custom:Y]-[date:custom:m]'
+  file_extensions: txt
+  max_filesize: ''
+  description_field: true
+  handler: 'default:file'
+  handler_settings: {  }
+field_type: file

core/modules/file/tests/fixtures/update/field.field.node.article.field_file_table_2677990.yml

@@ -0,0 +1,27 @@
+uuid: 44c7a590-ffcc-4534-b01c-b17b8d57ed48
+langcode: en
+status: true
+dependencies:
+  config:
+    - field.storage.node.field_file_table_2677990
+    - node.type.article
+  module:
+    - file
+id: node.article.field_file_table_2677990
+field_name: field_file_table_2677990
+entity_type: node
+bundle: article
+label: 'File table'
+description: ''
+required: false
+translatable: false
+default_value: {  }
+default_value_callback: ''
+settings:
+  file_directory: '[date:custom:Y]-[date:custom:m]'
+  file_extensions: txt
+  max_filesize: ''
+  description_field: true
+  handler: 'default:file'
+  handler_settings: {  }
+field_type: file

core/modules/file/tests/fixtures/update/field.storage.node.field_file_generic_2677990.yml

@@ -0,0 +1,23 @@
+uuid: a7eb470d-e538-4221-a8ac-57f989d92d8e
+langcode: en
+status: true
+dependencies:
+  module:
+    - file
+    - node
+id: node.field_file_generic_2677990
+field_name: field_file_generic_2677990
+entity_type: node
+type: file
+settings:
+  display_field: false
+  display_default: false
+  uri_scheme: public
+  target_type: file
+module: file
+locked: false
+cardinality: 1
+translatable: true
+indexes: {  }
+persist_with_no_fields: false
+custom_storage: false

core/modules/file/tests/fixtures/update/field.storage.node.field_file_table_2677990.yml

@@ -0,0 +1,23 @@
+uuid: 43113a5e-3e07-4234-b045-4aa4cd217dca
+langcode: en
+status: true
+dependencies:
+  module:
+    - file
+    - node
+id: node.field_file_table_2677990
+field_name: field_file_table_2677990
+entity_type: node
+type: file
+settings:
+  display_field: false
+  display_default: false
+  uri_scheme: public
+  target_type: file
+module: file
+locked: false
+cardinality: 1
+translatable: true
+indexes: {  }
+persist_with_no_fields: false
+custom_storage: false