The mysteries of Orchard’s OEmbedPart, or how to integrate YouTube videos

The media library picker field does a fine job of integrating and rendering external videos such as YouTube videos. If you want to customize the rendering of the videos, however, you’ll have to deal with the OEmbedPart (obtainable from contentItem.As<OEmbedPart>()). OEmbed is a fairly relaxed protocol that is designed to enable the integration of bits of a site into another. It can deal with images, videos, or even arbitrary HTML. Because it is so vague in what it can do, it’s rather hard to give it a representation other than something completely dynamic, and that's exactly what OEmbedPart is doing. Its only structured property is Source, which is the URL of the original content, one of the only constants in the data. The rest is available through the part’s indexer, by name: part[“title”] for example.

Here’s the format of the JSON video response that sites like YouTube return, copied from the oEmbed web site:

{
    "version": "1.0",
    "type": "video",
    "provider_name": "YouTube",
    "provider_url": "http://youtube.com/",
    "width": 425,
    "height": 344,
    "title": "Amazing Nintendo Facts",
    "author_name": "ZackScott",
    "author_url": "http://www.youtube.com/user/ZackScott",
    "html":
        "<object width=\"425\" height=\"344\">
            <param name=\"movie\" value=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"></param>
            <param name=\"allowFullScreen\" value=\"true\"></param>
            <param name=\"allowscriptaccess\" value=\"always\"></param>
            <embed src=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"
                type=\"application/x-shockwave-flash\" width=\"425\" height=\"344\"
                allowscriptaccess=\"always\" allowfullscreen=\"true\"></embed>
        </object>",
}

While one can use the Source property of the part to recover the original URL of the contents, the indexer allows access to each of the properties of the oEmbed document, such as “html”, the html to embed into the page to render the rich contents:

@Html.Raw(part["html"])

All other properties are also there for you to use. Many sites, YouTube included, will give more than what the oEmbed spec require however, so I encourage you to look for what you need in the stored document that can be found in the Infoset (the Data column of the Orchard_Framework_ContentItemRecord table, under the Data/OEmbedPart path). Here’s an example of that:

<OEmbedPart>
  <Source>https://www.youtube.com/watch?v=4I5Q3UXkGd0</Source>
  <thumbnail_height>360</thumbnail_height>
  <provider_url>http://www.youtube.com/</provider_url>
  <type>video</type>
  <width>480</width>
  <provider_name>YouTube</provider_name>
  <thumbnail_url>http://i.ytimg.com/vi/4I5Q3UXkGd0/hqdefault.jpg</thumbnail_url>
  <height>270</height>
  <version>1.0</version>
  <html>&lt;iframe width="480" height="270" src="http://www.youtube.com/embed/4I5Q3UXkGd0?feature=oembed" frameborder="0" allowfullscreen&gt;&lt;/iframe&gt;</html>
  <title>What Is The Resolution Of The Eye?</title>
  <author_name>Vsauce</author_name>
  <author_url>http://www.youtube.com/user/Vsauce</author_url>
  <thumbnail_width>480</thumbnail_width>
</OEmbedPart>

As you can see, there are quite a few additional properties, in particular “thumbnail_url”, “thumbnail_width”, and “thumbnail_height”, which can help you render a placeholder image, which is very useful when rendering in a list (the cost of rendering each video as an actual iframe would be prohibitive in those circumstances).

2 Comments

  • I didn't know you could use a MLPF to display external videos like YouTube videos. I assume it would work for other services such as Vimeo? Do you have a link you could point me to on how to do that if I don't want to use OEmbed and just want a standard include? Thanks!

  • Yes, it will work with any video service that supports oEmbed (that includes Vimeo). I don't get what you mean about using this without oEmbed.

Comments have been disabled for this content.