MediaSourceInterface
interface MediaSourceInterface implements PluginInspectionInterface, ConfigurableInterface, DependentPluginInterface, PluginFormInterface (View source)
Defines the interface for media source plugins.
Media sources provide the critical link between media items in Drupal and the actual media itself, which typically exists independently of Drupal. Each media source works with a certain kind of media. For example, local files and YouTube videos can both be catalogued in a similar way as media items, but they need very different handling to actually display them.
Each media type needs exactly one source. A single source can be used on many media types.
Examples of possible sources are:
- File: handles local files,
- Image: handles local images,
- oEmbed: handles resources that are exposed through the oEmbed standard,
- YouTube: handles YouTube videos,
- SoundCloud: handles SoundCloud audio,
- Instagram: handles Instagram posts,
- Twitter: handles tweets,
- ...
Their responsibilities are:
- Defining how media is represented (stored). Media sources are not responsible for actually storing the media. They only define how it is represented on a media item (usually using some kind of a field).
- Providing thumbnails. Media sources that are responsible for remote media will generally fetch the image from a third-party API and make it available for the local usage. Media sources that represent local media (such as images) will usually use some locally provided image. Media sources should fall back to a pre-defined default thumbnail if everything else fails.
- Validating a media item before it is saved. The entity constraint system will be used to ensure the valid structure of the media item. For example, media sources that represent remote media might check the URL or other identifier, while sources that represent local files might check the MIME type of the file.
- Providing a default name for a media item. This will save users from manually entering the name when it can be reliably set automatically. Media sources for local files will generally use the filename, while media sources for remote resources might obtain a title attribute through a third-party API. The name can always be overridden by the user.
- Providing metadata specific to the given media type. For example, remote media sources generally get information available through a third-party API and make it available to Drupal, while local media sources can expose things such as EXIF or ID3.
- Mapping metadata to the media item. Metadata that a media source exposes can automatically be mapped to the fields on the media item. Media sources will be able to define how this is done.
Constants
| METADATA_FIELD_EMPTY |
Default empty value for metadata fields. |
Methods
Gets the definition of the plugin implementation.
Sets the configuration for this plugin instance.
Calculates dependencies for the configured plugin.
Gets a list of metadata attributes provided by this plugin.
Gets the value for a metadata attribute for a given media item.
Get the source field definition for a media type.
Prepares the media type fields for this source in the view display.
Prepares the media type fields for this source in the form display.
Details
string
getPluginId()
Gets the plugin_id of the plugin instance.
array
getPluginDefinition()
Gets the definition of the plugin implementation.
array
getConfiguration()
Gets this plugin's configuration.
setConfiguration(array $configuration)
Sets the configuration for this plugin instance.
array
defaultConfiguration()
Gets default configuration for this plugin.
array
calculateDependencies()
Calculates dependencies for the configured plugin.
Dependencies are saved in the plugin's configuration entity and are used to determine configuration synchronization order. For example, if the plugin integrates with specific user roles, this method should return an array of dependencies listing the specified roles.
array
buildConfigurationForm(array $form, FormStateInterface $form_state)
Form constructor.
Plugin forms are embedded in other forms. In order to know where the plugin form is located in the parent form, #parents and #array_parents must be known, but these are not available during the initial build phase. In order to have these properties available when building the plugin form's elements, let this method return a form element that has a #process callback and build the rest of the form in the callback. By the time the callback is executed, the element's #parents and #array_parents properties will have been set by the form API. For more documentation on #parents and
array_parents, see \Drupal\Core\Render\Element\FormElement.
validateConfigurationForm(array $form, FormStateInterface $form_state)
Form validation handler.
submitConfigurationForm(array $form, FormStateInterface $form_state)
Form submission handler.
array
getMetadataAttributes()
Gets a list of metadata attributes provided by this plugin.
Most media sources have associated metadata, describing attributes such as:
- dimensions
- duration
- encoding
- date
- location
- permalink
- licensing information
- ...
This method should list all metadata attributes that a media source MAY offer. In other words: it is possible that a particular media item does not contain a certain attribute. For example: an oEmbed media source can contain both video and images. Images don't have a duration, but videos do.
(The term 'attributes' was chosen because it cannot be confused with 'fields' and 'properties', both of which are concepts in Drupal's Entity Field API.)
mixed|null
getMetadata(MediaInterface $media, string $attribute_name)
Gets the value for a metadata attribute for a given media item.
FieldDefinitionInterface|null
getSourceFieldDefinition(MediaTypeInterface $type)
Get the source field definition for a media type.
FieldConfigInterface
createSourceField(MediaTypeInterface $type)
Creates the source field definition for a type.
prepareViewDisplay(MediaTypeInterface $type, EntityViewDisplayInterface $display)
Prepares the media type fields for this source in the view display.
This method should normally call \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to configure the media type fields in the view display.
prepareFormDisplay(MediaTypeInterface $type, EntityFormDisplayInterface $display)
Prepares the media type fields for this source in the form display.
This method should normally call \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to configure the media type fields in the form display.
mixed
getSourceFieldValue(MediaInterface $media)
Get the primary value stored in the source field.