Apostrophe 3 Documentation

# 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.

← password →