Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\media;
|
Chris@0
|
4
|
Chris@18
|
5 use Drupal\Component\Plugin\ConfigurableInterface;
|
Chris@0
|
6 use Drupal\Component\Plugin\ConfigurablePluginInterface;
|
Chris@18
|
7 use Drupal\Component\Plugin\DependentPluginInterface;
|
Chris@0
|
8 use Drupal\Component\Plugin\PluginInspectionInterface;
|
Chris@14
|
9 use Drupal\Core\Entity\Display\EntityFormDisplayInterface;
|
Chris@14
|
10 use Drupal\Core\Entity\Display\EntityViewDisplayInterface;
|
Chris@0
|
11 use Drupal\Core\Plugin\PluginFormInterface;
|
Chris@0
|
12
|
Chris@0
|
13 /**
|
Chris@0
|
14 * Defines the interface for media source plugins.
|
Chris@0
|
15 *
|
Chris@0
|
16 * Media sources provide the critical link between media items in Drupal and the
|
Chris@0
|
17 * actual media itself, which typically exists independently of Drupal. Each
|
Chris@0
|
18 * media source works with a certain kind of media. For example, local files and
|
Chris@0
|
19 * YouTube videos can both be catalogued in a similar way as media items, but
|
Chris@0
|
20 * they need very different handling to actually display them.
|
Chris@0
|
21 *
|
Chris@0
|
22 * Each media type needs exactly one source. A single source can be used on many
|
Chris@0
|
23 * media types.
|
Chris@0
|
24 *
|
Chris@0
|
25 * Examples of possible sources are:
|
Chris@0
|
26 * - File: handles local files,
|
Chris@0
|
27 * - Image: handles local images,
|
Chris@0
|
28 * - oEmbed: handles resources that are exposed through the oEmbed standard,
|
Chris@0
|
29 * - YouTube: handles YouTube videos,
|
Chris@14
|
30 * - SoundCloud: handles SoundCloud audio,
|
Chris@0
|
31 * - Instagram: handles Instagram posts,
|
Chris@0
|
32 * - Twitter: handles tweets,
|
Chris@0
|
33 * - ...
|
Chris@0
|
34 *
|
Chris@0
|
35 * Their responsibilities are:
|
Chris@0
|
36 * - Defining how media is represented (stored). Media sources are not
|
Chris@0
|
37 * responsible for actually storing the media. They only define how it is
|
Chris@0
|
38 * represented on a media item (usually using some kind of a field).
|
Chris@0
|
39 * - Providing thumbnails. Media sources that are responsible for remote
|
Chris@0
|
40 * media will generally fetch the image from a third-party API and make
|
Chris@0
|
41 * it available for the local usage. Media sources that represent local
|
Chris@0
|
42 * media (such as images) will usually use some locally provided image.
|
Chris@0
|
43 * Media sources should fall back to a pre-defined default thumbnail if
|
Chris@0
|
44 * everything else fails.
|
Chris@0
|
45 * - Validating a media item before it is saved. The entity constraint system
|
Chris@0
|
46 * will be used to ensure the valid structure of the media item.
|
Chris@0
|
47 * For example, media sources that represent remote media might check the
|
Chris@0
|
48 * URL or other identifier, while sources that represent local files might
|
Chris@0
|
49 * check the MIME type of the file.
|
Chris@0
|
50 * - Providing a default name for a media item. This will save users from
|
Chris@0
|
51 * manually entering the name when it can be reliably set automatically.
|
Chris@0
|
52 * Media sources for local files will generally use the filename, while media
|
Chris@0
|
53 * sources for remote resources might obtain a title attribute through a
|
Chris@0
|
54 * third-party API. The name can always be overridden by the user.
|
Chris@0
|
55 * - Providing metadata specific to the given media type. For example, remote
|
Chris@0
|
56 * media sources generally get information available through a
|
Chris@0
|
57 * third-party API and make it available to Drupal, while local media sources
|
Chris@0
|
58 * can expose things such as EXIF or ID3.
|
Chris@0
|
59 * - Mapping metadata to the media item. Metadata that a media source exposes
|
Chris@0
|
60 * can automatically be mapped to the fields on the media item. Media
|
Chris@0
|
61 * sources will be able to define how this is done.
|
Chris@0
|
62 *
|
Chris@0
|
63 * @see \Drupal\media\Annotation\MediaSource
|
Chris@0
|
64 * @see \Drupal\media\MediaSourceBase
|
Chris@0
|
65 * @see \Drupal\media\MediaSourceManager
|
Chris@0
|
66 * @see \Drupal\media\MediaTypeInterface
|
Chris@0
|
67 * @see \Drupal\media\MediaSourceEntityConstraintsInterface
|
Chris@0
|
68 * @see \Drupal\media\MediaSourceFieldConstraintsInterface
|
Chris@0
|
69 * @see plugin_api
|
Chris@0
|
70 */
|
Chris@18
|
71 interface MediaSourceInterface extends PluginInspectionInterface, ConfigurableInterface, DependentPluginInterface, ConfigurablePluginInterface, PluginFormInterface {
|
Chris@0
|
72
|
Chris@0
|
73 /**
|
Chris@0
|
74 * Default empty value for metadata fields.
|
Chris@0
|
75 */
|
Chris@0
|
76 const METADATA_FIELD_EMPTY = '_none';
|
Chris@0
|
77
|
Chris@0
|
78 /**
|
Chris@0
|
79 * Gets a list of metadata attributes provided by this plugin.
|
Chris@0
|
80 *
|
Chris@0
|
81 * Most media sources have associated metadata, describing attributes
|
Chris@0
|
82 * such as:
|
Chris@0
|
83 * - dimensions
|
Chris@0
|
84 * - duration
|
Chris@0
|
85 * - encoding
|
Chris@0
|
86 * - date
|
Chris@0
|
87 * - location
|
Chris@0
|
88 * - permalink
|
Chris@0
|
89 * - licensing information
|
Chris@0
|
90 * - ...
|
Chris@0
|
91 *
|
Chris@0
|
92 * This method should list all metadata attributes that a media source MAY
|
Chris@0
|
93 * offer. In other words: it is possible that a particular media item does
|
Chris@0
|
94 * not contain a certain attribute. For example: an oEmbed media source can
|
Chris@0
|
95 * contain both video and images. Images don't have a duration, but
|
Chris@0
|
96 * videos do.
|
Chris@0
|
97 *
|
Chris@0
|
98 * (The term 'attributes' was chosen because it cannot be confused
|
Chris@0
|
99 * with 'fields' and 'properties', both of which are concepts in Drupal's
|
Chris@0
|
100 * Entity Field API.)
|
Chris@0
|
101 *
|
Chris@0
|
102 * @return array
|
Chris@0
|
103 * Associative array with:
|
Chris@0
|
104 * - keys: metadata attribute names
|
Chris@0
|
105 * - values: human-readable labels for those attribute names
|
Chris@0
|
106 */
|
Chris@0
|
107 public function getMetadataAttributes();
|
Chris@0
|
108
|
Chris@0
|
109 /**
|
Chris@0
|
110 * Gets the value for a metadata attribute for a given media item.
|
Chris@0
|
111 *
|
Chris@0
|
112 * @param \Drupal\media\MediaInterface $media
|
Chris@0
|
113 * A media item.
|
Chris@0
|
114 * @param string $attribute_name
|
Chris@0
|
115 * Name of the attribute to fetch.
|
Chris@0
|
116 *
|
Chris@0
|
117 * @return mixed|null
|
Chris@0
|
118 * Metadata attribute value or NULL if unavailable.
|
Chris@0
|
119 */
|
Chris@0
|
120 public function getMetadata(MediaInterface $media, $attribute_name);
|
Chris@0
|
121
|
Chris@0
|
122 /**
|
Chris@0
|
123 * Get the source field definition for a media type.
|
Chris@0
|
124 *
|
Chris@0
|
125 * @param \Drupal\media\MediaTypeInterface $type
|
Chris@0
|
126 * A media type.
|
Chris@0
|
127 *
|
Chris@0
|
128 * @return \Drupal\Core\Field\FieldDefinitionInterface|null
|
Chris@0
|
129 * The source field definition, or NULL if it doesn't exist or has not been
|
Chris@0
|
130 * configured yet.
|
Chris@0
|
131 */
|
Chris@0
|
132 public function getSourceFieldDefinition(MediaTypeInterface $type);
|
Chris@0
|
133
|
Chris@0
|
134 /**
|
Chris@0
|
135 * Creates the source field definition for a type.
|
Chris@0
|
136 *
|
Chris@0
|
137 * @param \Drupal\media\MediaTypeInterface $type
|
Chris@0
|
138 * The media type.
|
Chris@0
|
139 *
|
Chris@0
|
140 * @return \Drupal\field\FieldConfigInterface
|
Chris@0
|
141 * The unsaved field definition. The field storage definition, if new,
|
Chris@0
|
142 * should also be unsaved.
|
Chris@0
|
143 */
|
Chris@0
|
144 public function createSourceField(MediaTypeInterface $type);
|
Chris@0
|
145
|
Chris@14
|
146 /**
|
Chris@14
|
147 * Prepares the media type fields for this source in the view display.
|
Chris@14
|
148 *
|
Chris@14
|
149 * This method should normally call
|
Chris@14
|
150 * \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or
|
Chris@14
|
151 * \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to
|
Chris@14
|
152 * configure the media type fields in the view display.
|
Chris@14
|
153 *
|
Chris@14
|
154 * @param \Drupal\media\MediaTypeInterface $type
|
Chris@14
|
155 * The media type which is using this source.
|
Chris@14
|
156 * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
|
Chris@14
|
157 * The display which should be prepared.
|
Chris@14
|
158 *
|
Chris@14
|
159 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
|
Chris@14
|
160 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
|
Chris@14
|
161 */
|
Chris@14
|
162 public function prepareViewDisplay(MediaTypeInterface $type, EntityViewDisplayInterface $display);
|
Chris@14
|
163
|
Chris@14
|
164 /**
|
Chris@14
|
165 * Prepares the media type fields for this source in the form display.
|
Chris@14
|
166 *
|
Chris@14
|
167 * This method should normally call
|
Chris@14
|
168 * \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or
|
Chris@14
|
169 * \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to
|
Chris@14
|
170 * configure the media type fields in the form display.
|
Chris@14
|
171 *
|
Chris@14
|
172 * @param \Drupal\media\MediaTypeInterface $type
|
Chris@14
|
173 * The media type which is using this source.
|
Chris@14
|
174 * @param \Drupal\Core\Entity\Display\EntityFormDisplayInterface $display
|
Chris@14
|
175 * The display which should be prepared.
|
Chris@14
|
176 *
|
Chris@14
|
177 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
|
Chris@14
|
178 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
|
Chris@14
|
179 */
|
Chris@14
|
180 public function prepareFormDisplay(MediaTypeInterface $type, EntityFormDisplayInterface $display);
|
Chris@14
|
181
|
Chris@14
|
182 /**
|
Chris@14
|
183 * Get the primary value stored in the source field.
|
Chris@14
|
184 *
|
Chris@14
|
185 * @param MediaInterface $media
|
Chris@14
|
186 * A media item.
|
Chris@14
|
187 *
|
Chris@14
|
188 * @return mixed
|
Chris@14
|
189 * The source value.
|
Chris@14
|
190 *
|
Chris@14
|
191 * @throws \RuntimeException
|
Chris@14
|
192 * If the source field for the media source is not defined.
|
Chris@14
|
193 */
|
Chris@14
|
194 public function getSourceFieldValue(MediaInterface $media);
|
Chris@14
|
195
|
Chris@0
|
196 }
|