# oembed
A oembed
field supports the user in embedding media hosted by any oembed—compatible hosting site (opens new window), or any site for which you have provided an oembetter (opens new window) 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. |
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 (opens new window) 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.