diff --git a/core/lib/Drupal/Core/Field/FieldTypePluginManager.php b/core/lib/Drupal/Core/Field/FieldTypePluginManager.php index 565fa4e..26ade20 100644 --- a/core/lib/Drupal/Core/Field/FieldTypePluginManager.php +++ b/core/lib/Drupal/Core/Field/FieldTypePluginManager.php @@ -139,7 +139,9 @@ public function getUiDefinitions() { $definitions['field_ui:' . $id . ':' . $key] = [ 'label' => $option['label'], ] + $definition; - + if (isset($option['description'])) { + $definitions['field_ui:' . $id . ':' . $key]['description'] = $option['description']; + } if (isset($option['category'])) { $definitions['field_ui:' . $id . ':' . $key]['category'] = $option['category']; } diff --git a/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php b/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php index 70f9dc9..51c97c8 100644 --- a/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php +++ b/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php @@ -633,6 +633,12 @@ public static function settingsAjaxSubmit($form, FormStateInterface $form_state) public static function getPreconfiguredOptions() { $options = []; + $description = ''; + $plugin_definition = \Drupal::service('plugin.manager.field.field_type')->getDefinition('entity_reference'); + if (isset($plugin_definition['description'])) { + $description = $plugin_definition['description']; + } + // Add all the commonly referenced entity types as distinct pre-configured // options. $entity_types = \Drupal::entityManager()->getDefinitions(); @@ -644,6 +650,7 @@ public static function getPreconfiguredOptions() { foreach ($common_references as $entity_type) { $options[$entity_type->id()] = [ 'label' => $entity_type->getLabel(), + 'description' => $description, 'field_storage_config' => [ 'settings' => [ 'target_type' => $entity_type->id(), diff --git a/core/lib/Drupal/Core/Field/PreconfiguredFieldUiOptionsInterface.php b/core/lib/Drupal/Core/Field/PreconfiguredFieldUiOptionsInterface.php index 684168a..35d5e6f 100644 --- a/core/lib/Drupal/Core/Field/PreconfiguredFieldUiOptionsInterface.php +++ b/core/lib/Drupal/Core/Field/PreconfiguredFieldUiOptionsInterface.php @@ -24,6 +24,8 @@ * @return mixed[][] * A multi-dimensional array with string keys and the following structure: * - label: The label to show in the field type selection list. + * - description: (optional) The description to be used when exposing this + * field in the field type selection list. * - category: (optional) The category in which to put the field label. * Defaults to the category of the field type. * - field_storage_config: An array with the following supported keys: diff --git a/core/modules/field_ui/src/Form/FieldStorageAddForm.php b/core/modules/field_ui/src/Form/FieldStorageAddForm.php index 584cc96..b355491 100644 --- a/core/modules/field_ui/src/Form/FieldStorageAddForm.php +++ b/core/modules/field_ui/src/Form/FieldStorageAddForm.php @@ -104,7 +104,8 @@ public function buildForm(array $form, FormStateInterface $form_state, $entity_t // Gather valid field types. $field_type_options = []; - foreach ($this->fieldTypePluginManager->getGroupedDefinitions($this->fieldTypePluginManager->getUiDefinitions()) as $category => $field_types) { + $ui_definitions = $this->fieldTypePluginManager->getGroupedDefinitions($this->fieldTypePluginManager->getUiDefinitions()); + foreach ($ui_definitions as $category => $field_types) { foreach ($field_types as $name => $field_type) { $field_type_options[$category][$name] = $field_type['label']; } @@ -145,6 +146,36 @@ public function buildForm(array $form, FormStateInterface $form_state, $entity_t ]; } + // Show the field description, if it exists. + $form['description_wrapper'] = [ + '#type' => 'container', + '#states' => [ + '!visible' => [ + ':input[name="new_storage_type"]' => ['value' => ''], + ], + ], + ]; + $i = 0; + foreach ($ui_definitions as $category => $field_types) { + foreach ($field_types as $name => $field_type) { + if (empty($field_type['description'])) { + continue; + } + $form['description_wrapper']["description_{$name}_{$i}"] = [ + '#type' => 'container', + '#states' => [ + 'visible' => [ + ':input[name="new_storage_type"]' => ['value' => $name], + ], + ], + ]; + $form['description_wrapper']["description_{$name}_{$i}"]['description'] = [ + '#markup' => $field_type['description'], + ]; + $i++; + } + } + // Field label and field_name. $form['new_storage_wrapper'] = [ '#type' => 'container', diff --git a/core/modules/field_ui/tests/src/FunctionalJavascript/UiDescriptionsTest.php b/core/modules/field_ui/tests/src/FunctionalJavascript/UiDescriptionsTest.php new file mode 100644 index 0000000..f6ec8d3 --- /dev/null +++ b/core/modules/field_ui/tests/src/FunctionalJavascript/UiDescriptionsTest.php @@ -0,0 +1,67 @@ +drupalLogin($this->drupalCreateUser([ + 'access administration pages', + 'administer node fields', + 'view the administration theme', + ])); + } + + /** + * Tests the descriptions of some fields. + */ + public function testFieldDescriptions() { + $page = $this->getSession()->getPage(); + $assert_session = $this->assertSession(); + + $node_type = $this->drupalCreateContentType(); + + $this->drupalGet("admin/structure/types/manage/{$node_type->id()}/fields/add-field"); + + // Check that the description wrapper is only visible after you select that + // element from the list. + $assert_session->optionExists('edit-new-storage-type', 'boolean'); + $boolean_description_element = $assert_session->elementExists('css', '#edit-description-boolean-0'); + $this->assertFalse($boolean_description_element->isVisible()); + $page->selectFieldOption('edit-new-storage-type', 'boolean'); + $boolean_description_element = $assert_session->elementExists('css', '#edit-description-boolean-0'); + $this->assertTrue($boolean_description_element->isVisible()); + + // Make sure the expected texts from the plugin annotations (or overriden + // strings) are present on the page. + $manager = \Drupal::service('plugin.manager.field.field_type'); + $file_description = $manager->getDefinition('file')['description']; + $assert_session->pageTextContains($file_description); + $image_description = $manager->getDefinition('image')['description']; + $assert_session->pageTextContains($image_description); + $media_description = 'Use a "Media" field to reference assets such as files, images, videos and more. You will be able to select which media types can be referenced in the next steps.'; + $assert_session->pageTextContains($media_description); + } + +} diff --git a/core/modules/file/src/Plugin/Field/FieldType/FileItem.php b/core/modules/file/src/Plugin/Field/FieldType/FileItem.php index 542be12..df5cc4c 100644 --- a/core/modules/file/src/Plugin/Field/FieldType/FileItem.php +++ b/core/modules/file/src/Plugin/Field/FieldType/FileItem.php @@ -18,7 +18,7 @@ * @FieldType( * id = "file", * label = @Translation("File"), - * description = @Translation("This field stores the ID of a file as an integer value."), + * description = @Translation("Use a 'File' reference when you want to upload an arbitrary file to an entity, generally without re-usability needs. If in doubt, 'Media' references should be preferred instead."), * category = @Translation("Reference"), * default_widget = "file_generic", * default_formatter = "file_default", diff --git a/core/modules/image/src/Plugin/Field/FieldType/ImageItem.php b/core/modules/image/src/Plugin/Field/FieldType/ImageItem.php index 67a15a7..19499af 100644 --- a/core/modules/image/src/Plugin/Field/FieldType/ImageItem.php +++ b/core/modules/image/src/Plugin/Field/FieldType/ImageItem.php @@ -18,7 +18,7 @@ * @FieldType( * id = "image", * label = @Translation("Image"), - * description = @Translation("This field stores the ID of an image file as an integer value."), + * description = @Translation("Use an 'Image' reference when you want to upload an image to on entity, generally without re-usability needs. If in doubt, 'Media' references should be preferred instead."), * category = @Translation("Reference"), * default_widget = "image_image", * default_formatter = "image", diff --git a/core/modules/media/media.module b/core/modules/media/media.module index 5df059c..a83eb35 100644 --- a/core/modules/media/media.module +++ b/core/modules/media/media.module @@ -109,9 +109,13 @@ function media_field_ui_preconfigured_options_alter(array &$options, $field_type return; } - // Set the default formatter for media in entity reference fields to be the - // "Rendered entity" formatter. if (!empty($options['media'])) { + // Set the default formatter for media in entity reference fields to be the + // "Rendered entity" formatter. $options['media']['entity_view_display']['type'] = 'entity_reference_entity_view'; + + // Override the "entity_reference" field description text with a + // media-related one. + $options['media']['description'] = t('Use a "Media" field to reference assets such as files, images, videos and more. You will be able to select which media types can be referenced in the next steps.'); } }