Create module documentation page on drupal.org [#3227778]

Problem/Motivation

Currently, the usage documentation for this module exists in two places:

The project overview page
In comments within src/Element/MediaLibrary.php

For the 2.x branch, the documentation is out of sync between the two places.

Proposed resolution

Create a project documentation node on drupal.org that can act as a canonical source of truth for how to use the element plugin provided by this module. This could allow the project page to link to the documentation and can allow for the removal of example usage from the source code comments.

Mock up

Usage

The form API element can be used much like any other render element type. In addition to the usual render array properties, it comes with a couple of extra configurable properties and quirks.

Property	Description	Default value	Allowed value(s)
#default_value	This is the same property as defined by all render elements, but with some unique value options.	NULL	NULL - no media entities will be selected integer - a single media entity will be selected by ID comma-delimited string - multiple media entities will be selected by ID
#allowed_bundles	Only media entities of the specified bundle(s) will be available for selection.	FALSE	An array of strings A value must be provided, otherwise a fatal PHP error will occur!

Property

Description

Default value

Allowed value(s)

#default_value

This is the same property as defined by all render elements, but with some unique value options.

NULL

NULL - no media entities will be selected

integer - a single media entity will be selected by ID

comma-delimited string - multiple media entities will be selected by ID

#allowed_bundles

Only media entities of the specified bundle(s) will be available for selection.

FALSE

An array of strings

A value must be provided, otherwise a fatal PHP error will occur!

Examples

This example allows a single image to be selected. By default, no image is pre-selected.

$form['image'] = [
  '#type' => 'media_library',
  '#allowed_bundles' => ['image'],
  '#title' => t('Upload your image'),
  '#default_value' => $form_state->getValue('image') ?? NULL,
  '#description' => t('Upload or select your profile image.'),
  '#cardinality' => 1,
];

This example allows for two images to be selected. By default, an image with ID 1 is pre-selected if such an image exists.

$form['images'] = [
  '#type' => 'media_library',
  '#allowed_bundles' => ['image'],
  '#title' => t('Upload your image(s)'),
  '#default_value' => $form_state->getValue('images') ?? 1,
  '#description' => t('Upload or select your profile image(s).'),
  '#cardinality' => 2,
];

This example allows for an unlimited number of videos to be selected. By default, videos with ID 1 and 2 are pre-selected if such videos exist.

use Drupal\Core\Field\FieldStorageDefinitionInterface;

// ...
// ...

$form['videos'] = [
  '#type' => 'media_library',
  '#allowed_bundles' => ['video'],
  '#title' => t('Upload your video(s)'),
  '#default_value' => $form_state->getValue('videos') ?? '1,2',
  '#description' => t('Upload or select your video(s).'),
  '#cardinality' => FieldStorageDefinitionInterface::CARDINALITY_UNLIMITED,
];

Remaining tasks

Create documentation node on drupal.org
Copy / consolidate documentation from various sources into node
Review documentation
Remove or update usage documentation from source code comments
Merge this issue, publish the documentation node, and update the project overview.