Issue #2964789 by phenaproxima, capysara, J.Gayathri, webchick, seanB,...

Issue #2964789 by phenaproxima, capysara, J.Gayathri, webchick, seanB, samuel.mortenson, Wim Leers, xjm, balsama, katherined, mradcliffe, JeroenT, bnjmnm, starshaped, oknate, RoloDMonkey: Document the Media Library module

(cherry picked from commit 6ea36484)

core/modules/media_library/media_library.module

@@ -16,6 +16,7 @@
 use Drupal\Core\Routing\RouteMatchInterface;
 use Drupal\Core\Session\AccountInterface;
 use Drupal\Core\Template\Attribute;
+use Drupal\Core\Url;
 use Drupal\image\Entity\ImageStyle;
 use Drupal\image\Plugin\Field\FieldType\ImageItem;
 use Drupal\media\MediaTypeForm;
@@ -38,7 +39,35 @@ function media_library_help($route_name, RouteMatchInterface $route_match) {
   switch ($route_name) {
     case 'help.page.media_library':
       $output = '<h3>' . t('About') . '</h3>';
-      $output .= '<p>' . t('The Media Library module overrides the /admin/content/media view to provide a rich visual interface for performing administrative operations on media. For more information, see the <a href=":media">online documentation for the Media Library module</a>.', [':media' => 'https://www.drupal.org/docs/8/core/modules/media']) . '</p>';
+      $output .= '<p>' . t('The Media Library module provides a rich, visual interface for managing media, and allows media to be reused in entity reference fields or embedded into text content. It overrides the <a href=":media-collection">media administration page</a>, allowing users to toggle between the existing table-style interface and a new grid-style interface for browsing and performing administrative operations on media.', [
+        ':media-collection' => Url::fromRoute('entity.media.collection')->toString(),
+      ]) . '</p>';
+      $output .= '<p>' . t('To learn more about media management, begin by reviewing the <a href=":media-help">documentation for the Media module</a>. For more information about the media library and related functionality, see the <a href=":media-library-handbook">online documentation for the Media Library module</a>.', [
+        ':media-help' => Url::fromRoute('help.page', ['name' => 'media'])->toString(),
+        ':media-library-handbook' => 'https://www.drupal.org/docs/8/core/modules/media-library-module',
+      ]) . '</p>';
+      $output .= '<h3>' . t('Selection dialog') . '</h3>';
+      $output .= '<p>' . t('When selecting media for an entity reference field or a text editor, Media Library opens a modal dialog to help users easily find and select media. The modal dialog can toggle between a grid-style and table-style interface, and new media items can be uploaded directly into it.') . '</p>';
+      $output .= '<p>' . t('Within the dialog, media items are divided up by type. If more than one media type can be selected by the user, the available types will be displayed as a set of vertical tabs. To users who have appropriate permissions, each media type may also present a short form allowing you to upload or create new media items of that type.') . '</p>';
+      $output .= '<h3>' . t('Uses') . '</h3>';
+      $output .= '<dl>';
+      $output .= '<dt>' . t('Grid-style vs. table-style interface') . '</dt>';
+      $output .= '<dd>' . t('The Media Library module provides a new grid-style interface for the media administration page that displays media as thumbnails, with minimal textual information, allowing users to visually browse media in their site. The existing table-style interface is better suited to displaying additional information about media items, in addition to being more accessible to users with assistive technology.') . '</dd>';
+      $output .= '<dt>' . t('Reusing media in entity reference fields') . '</dt>';
+      $output .= '<dd>' . t('Any entity reference field that references media can use the media library. To enable, configure the form display for the field to use the "Media library" widget.') . '</dd>';
+      $output .= '<dt>' . t('Embedding media in text content') . '</dt>';
+      $output .= '<dd>' . t('To use the media library within CKEditor, you must add the "Insert from Media Library" button to the CKEditor toolbar, and enable the "Embed media" filter in the text format associated with the text editor.') . '</dd>';
+      $output .= '</dl>';
+      $output .= '<h3>' . t('Customize') . '</h3>';
+      $output .= '<ul>';
+      $output .= '<li>' . t('Both the table-style and grid-style interfaces are regular views and can be customized via the Views UI, including sorting and filtering. This is the case for both the administration page and the modal dialog.') . '</li>';
+      $output .= '<li>' . t('In the grid-style interface, which fields are displayed (including which image style is used for images) can be customized by configuring the "Media library" view mode for each of your <a href=":media-types">media types</a>. The thumbnail images in the grid-style interface can be customized by configuring the "Media Library thumbnail (220×220)" image style.', [
+        ':media-types' => Url::fromRoute('entity.media_type.collection')->toString(),
+      ]) . '</li>';
+      $output .= '<li>' . t('When adding new media items within the modal dialog, which fields are displayed can be customized by configuring the "Media library" form mode for each of your <a href=":media-types">media types</a>.', [
+        ':media-types' => Url::fromRoute('entity.media_type.collection')->toString(),
+      ]) . '</li>';
+      $output .= '</ul>';
       return $output;
   }
 }