1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
<?php
namespace Drupal\media;
use Drupal\Component\Plugin\ConfigurableInterface;
use Drupal\Component\Plugin\DependentPluginInterface;
use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\Core\Entity\Display\EntityFormDisplayInterface;
use Drupal\Core\Entity\Display\EntityViewDisplayInterface;
use Drupal\Core\Plugin\PluginFormInterface;
/**
* 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.
*
* @see \Drupal\media\Annotation\MediaSource
* @see \Drupal\media\MediaSourceBase
* @see \Drupal\media\MediaSourceManager
* @see \Drupal\media\MediaTypeInterface
* @see \Drupal\media\MediaSourceEntityConstraintsInterface
* @see \Drupal\media\MediaSourceFieldConstraintsInterface
* @see plugin_api
*/
interface MediaSourceInterface extends PluginInspectionInterface, ConfigurableInterface, DependentPluginInterface, PluginFormInterface {
/**
* Default empty value for metadata fields.
*/
const METADATA_FIELD_EMPTY = '_none';
/**
* 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.)
*
* @return array
* Associative array with:
* - keys: metadata attribute names
* - values: human-readable labels for those attribute names
*/
public function getMetadataAttributes();
/**
* Gets the value for a metadata attribute for a given media item.
*
* @param \Drupal\media\MediaInterface $media
* A media item.
* @param string $attribute_name
* Name of the attribute to fetch.
*
* @return mixed|null
* Metadata attribute value or NULL if unavailable.
*/
public function getMetadata(MediaInterface $media, $attribute_name);
/**
* Get the source field definition for a media type.
*
* @param \Drupal\media\MediaTypeInterface $type
* A media type.
*
* @return \Drupal\Core\Field\FieldDefinitionInterface|null
* The source field definition, or NULL if it doesn't exist or has not been
* configured yet.
*/
public function getSourceFieldDefinition(MediaTypeInterface $type);
/**
* Creates the source field definition for a type.
*
* @param \Drupal\media\MediaTypeInterface $type
* The media type.
*
* @return \Drupal\field\FieldConfigInterface
* The unsaved field definition. The field storage definition, if new,
* should also be unsaved.
*/
public function createSourceField(MediaTypeInterface $type);
/**
* 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.
*
* @param \Drupal\media\MediaTypeInterface $type
* The media type which is using this source.
* @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
* The display which should be prepared.
*
* @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
* @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
*/
public function prepareViewDisplay(MediaTypeInterface $type, EntityViewDisplayInterface $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.
*
* @param \Drupal\media\MediaTypeInterface $type
* The media type which is using this source.
* @param \Drupal\Core\Entity\Display\EntityFormDisplayInterface $display
* The display which should be prepared.
*
* @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
* @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
*/
public function prepareFormDisplay(MediaTypeInterface $type, EntityFormDisplayInterface $display);
/**
* Get the primary value stored in the source field.
*
* @param MediaInterface $media
* A media item.
*
* @return mixed
* The source value, or NULL if the media item's source field is empty.
*
* @throws \RuntimeException
* If the source field for the media source is not defined.
*/
public function getSourceFieldValue(MediaInterface $media);
}
|
