From 48229e83d2290f7c6c8d2842802f2258313904d2 Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Thu, 17 Oct 2019 15:52:59 +0100
Subject: [PATCH] Issue #3088476 by phenaproxima, Wim Leers: Document Media
 Library's API and architecture

(cherry picked from commit 2607278f2c6cfa6382337216923913707ed47539)
---
 .../media_library/media_library.api.php       | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 core/modules/media_library/media_library.api.php

diff --git a/core/modules/media_library/media_library.api.php b/core/modules/media_library/media_library.api.php
new file mode 100644
index 0000000000..5c33600ff5
--- /dev/null
+++ b/core/modules/media_library/media_library.api.php
@@ -0,0 +1,93 @@
+<?php
+
+/**
+ * @file
+ * Documentation related to Media Library.
+ */
+
+/**
+ * @defgroup media_library_architecture Media Library Architecture
+ * @{
+ *
+ * Media Library is a UI for the core Media module. It provides a visual
+ * interface for users to manage media in their site, and it allows authors to
+ * visually select media for use in entity reference and text fields, using a
+ * modal dialog.
+ *
+ * In order to provide a consistent user experience, Media Library is
+ * intentionally opinionated, with few extension points and no hooks. Most of
+ * its code is internal and should not be extended or instantiated by external
+ * code.
+ *
+ * @section openers Openers
+ * Interaction with the modal media library dialog is mediated by "opener"
+ * services. All openers must implement
+ * \Drupal\media_library\MediaLibraryOpenerInterface.
+ *
+ * Openers are responsible for determining access to the media library, and for
+ * generating an AJAX response when the user has finished selecting media items
+ * in the library. An opener is a "bridge" between the opinionated media library
+ * modal dialog and whatever is consuming it, allowing the dialog to be
+ * triggered in a way that makes sense for that particular consumer. Examples in
+ * Drupal core include entity reference fields and text editors.
+ *
+ * @see \Drupal\media_library\MediaLibraryOpenerInterface
+ * @see \Drupal\media_library\MediaLibraryEditorOpener
+ * @see \Drupal\media_library\MediaLibraryFieldWidgetOpener
+ *
+ * @section state Modal dialog state
+ * When the media library modal is used, its configuration and state (such as
+ * how many items are currently selected, the maximum number that can be
+ * selected, which media types the user is allowed to see, and so forth) are
+ * stored in an instance of \Drupal\media_library\MediaLibraryState. The state
+ * object also stores the service ID of the opener being used, as well as any
+ * additional parameters or data that are specific to that opener.
+ *
+ * The media library state is passed between the user and the server in the
+ * URL's query parameters. Therefore, the state is also protected by a hash in
+ * order to prevent tampering.
+ *
+ * @see \Drupal\media_library\MediaLibraryState
+ *
+ * @section add_form Adding media in the dialog
+ * Users with appropriate permissions can add media to the library from directly
+ * within the modal dialog.
+ *
+ * This interaction is implemented using forms, and is customizable by modules.
+ * Since the media library is segmented by media type, each media type can
+ * expose a different form for adding media of that type; the type's source
+ * plugin specifies the actual form class to use. Here is an example of a media
+ * source plugin definition which provides an add form for the media library:
+ *
+ * @code
+ * @MediaSource(
+ *   id = "file",
+ *   label = @Translation("File"),
+ *   description = @Translation("Use local files for reusable media."),
+ *   allowed_field_types = {"file"},
+ *   default_thumbnail_filename = "generic.png",
+ *   forms = {
+ *     "media_library_add" = "\Drupal\media_library\Form\FileUploadForm",
+ *   },
+ * )
+ * @endcode
+ *
+ * This can also be done in hook_media_source_info_alter(). For example:
+ *
+ * @code
+ * function example_media_source_info_alter(array &$sources) {
+ *   $sources['file']['forms']['media_library_add'] = "\Drupal\media_library\Form\FileUploadForm";
+ * }
+ * @endcode
+ *
+ * The add form is a standard form class, and can be altered by modules and
+ * themes just like any other form. For easier implementation, it is recommended
+ * that modules extend \Drupal\media_library\Form\AddFormBase when providing add
+ * forms.
+ *
+ * @see \Drupal\media_library\Form\AddFormBase
+ * @see \Drupal\media_library\Form\FileUploadForm
+ * @see \Drupal\media_library\Form\OEmbedForm
+ *
+ * @}
+ */
-- 
GitLab