oembed
A oembed field supports the user in embedding media hosted by any oembed—compatible hosting site, or any site for which you have provided an oembetter filter via the @apostrophecms/oembed module.
The field will immediately preview the media embed after entering a valid URL.
The database value of the field will have url, title and thumbnail properties. title and thumbnail are snapshots from the oembed response at the time the field was saved. thumbnail is the URL of a thumbnail image as provided by the oembed response. Developers should retrieve the full embed code in client-side code to get the latest version available.
Module field definition
// Configuring the `video` field in a module's `fields.add` subsection:
video: {
type: 'oembed',
label: 'Featured video'
}Settings
Required
| Property | Type | Default | Description |
|---|---|---|---|
label | String | n/a | Sets the visible label for the field in the UI |
type | String | n/a | Specifies the field type (float for this type) |
Optional
| Property | Type | Default | Description |
|---|---|---|---|
help | String | n/a | Help text for the content editor |
htmlHelp | String | n/a | Help text with support for HTML markup |
if | Object | {} | Conditions to meet before the field is active. See the guide for details. |
requiredIf | Object | {} | Conditions to meet before the field is required. See the guide for details. |
hidden | Boolean | false | If true, the field is hidden |
required | Boolean | false | If true, the field is mandatory |
readOnly | Boolean | false | If true, prevents the user from editing the field value |
Use in templates
Simplest usage could involve simply printing the thumbnail image (if available) and linking to the media:
{% if data.piece.video and data.piece.video.thumbnail %}
{% set video = data.piece.video %}
<a href="{{ video.url }}">
<img src="{{ video.thumbnail }}" alt="{{ video.title }}">
</a>
{% endif %}More likely, you will want to add the full embed code from the media source. This should be done in client-side JavaScript. Apostrophe provides an API route to get that.
Submit a GET request to /api/v1/@apostrophecms/oembed/query with the media URL as the url query parameter. A successful response will be an object with several properties to help place and style the embed, including an html property with the actual HTML markup to embed.
The @apostrophecms/video-widget widget provides a full-featured implementation. It includes a widget player that uses that API route to retrieve the full embed code and then replaces a placeholder HTML element with that code. See that widget for a suggested implementation.