Skip to content

Instantly share code, notes, and snippets.

@theefer

theefer/embeds-requirements.md

Last active December 22, 2015 17:38
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save theefer/6507236 to your computer and use it in GitHub Desktop.
Save theefer/6507236 to your computer and use it in GitHub Desktop.
Download ZIP
More details
Raw
embeds-requirements.md

Embed Requirements

Expectations

  • Declarative markup: semantic content (eg Twitter), degrades gracefully (what if cached, read offline, in Pocket, etc), ideally not iframe? (eg not YouTube)
  • Progressively enhanced: static fallback (eg Twitter, Guardian Video & Comment), ideally feature detection (eg YouTube)
  • Controllable lifecycle: plug and play by default, let host optionally control init and context
  • Lightweight: minimal impact on bandwidth & mem/cpu (eg Flickr, not Twitter)
  • Responsive: fit in parent element
  • Addressable: canonical URL for the embedded content, can be linked to as fallback

Also:

  • SSL-agnostic: work over HTTP and HTTPS
  • Support being added programmatically to a page
  • Support being taken out and put back into the DOM

Resolvers

  • Twitter: tweet
  • Embedly: YouTube, Vimeo, AudioBoo, Google Maps, Google Docs, etc
  • Guardian Discussion: Guardian comment
  • Guardian API: Guardian video
  • Guardian Witness: Guardian Witness contribution

Examples

Twitter

<blockquote class="twitter-tweet"><p>Coast by Opera. Is it just me or is that trailer slightly over-dramatic? <a href="http://t.co/m4YZi5xL8A">http://t.co/m4YZi5xL8A</a></p>&mdash; Sébastien Cevey (@theefer) <a href="https://twitter.com/theefer/statuses/377077814379679746">September 9, 2013</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

YouTube

<iframe width="500" height="375" src="http://www.youtube.com/embed/5QkTRT2skKI?feature=oembed" frameborder="0" allowfullscreen></iframe>

AudioBoo

<iframe frameborder="0" scrolling="no" src="https://audioboo.fm/boos/1412135-syria-s-refugees-continue-to-arrive-in-northern-iraq/embed" title="Audioboo player" width="500" height="145" border="0"></iframe>

Google Maps

<iframe width="425" height="350" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" src="https://maps.google.co.uk/?ie=UTF8&amp;ll=51.528642,-0.101599&amp;spn=0.744144,2.110748&amp;t=m&amp;z=10&amp;output=embed"></iframe><br /><small><a href="https://maps.google.co.uk/?ie=UTF8&amp;ll=51.528642,-0.101599&amp;spn=0.744144,2.110748&amp;t=m&amp;z=10&amp;source=embed" style="color:#0000FF;text-align:left">View Larger Map</a></small>

Guardian Video

<video data-media-id="gu-video-416887871" class="gu-video" controls="controls" poster="http://static.guim.co.uk/sys-images/Guardian/Pix/audio/video/2013/9/10/1378807791943/Content-The-week-in-TV-Ed-012.jpg"> <source src="http://cdn.theguardian.tv/mainwebsite/2013/9/9/130909TellyAddict-16x9.mp4"></source><source src="http://cdn.theguardian.tv/3gp/large/2013/9/9/130909TellyAddict_3gpLg16x9.3gp"></source><source src="http://cdn.theguardian.tv/ad/2013/9/9/130909TellyAddict/130909TellyAddict.m3u8"></source><source src="http://cdn.theguardian.tv/3gp/small/2013/9/9/130909TellyAddict_3gpSml16x9.3gp"></source><source src="http://cdn.theguardian.tv/webM/640/2013/9/9/130909TellyAddict_vpx.webm"></source><source src="http://cdn.theguardian.tv/connectedTV/1280/2013/9/9/130909TellyAddict-720.mp4"></source> </video>

Guardian Comment

<div class="d2-comment-embedded" itemscope itemtype="http://schema.org/Comment"> <div class="d2-left-col"> <a href="http://www.theguardian.com/discussion/user/id/4554017" title="View Circumbendibus’s profile"> <img class="d2-avatar" src="http://static.guim.co.uk/sys-images/discussion/avatars/2011/09/26/Circumbendibus/adea1b48-7c01-4b77-8c7c-61470f895a6e/60x60.png" height="40" width="40" alt="User avatar for Circumbendibus"> </a> </div> <div class="d2-right-col"> <div itemscope itemprop="author" itemtype="http://schema.org/Person"> <a class="d2-username" href="http://www.theguardian.com/discussion/user/id/4554017" title="View Circumbendibus’s profile" itemprop="url"> <span itemprop="givenName">Circumbendibus</span> </a> </div> <div class="d2-permalink"> <a class="d2-datetime" href="http://discussion.theguardian.com/comment-permalink/26836069" title="Link to this comment" itemprop="datePublished">10 September 2013 10:59am</a> </div> <div class="d2-body" itemprop="text"><p>When will the French realise they are bit players on the geo-political stage? Desperate to appear relevant in the modern age, our French cousins appear ridiculous.</p></div> </div> </div>

Guardian Witness

<figure class="element element-witness element-witness-image" itemscope itemtype="http://schema.org/ImageObject" data-media-id="https://witness.theguardian.com/assignment/5220a453e4b07d9848ba9fdb/522390">
		<div class="element-witness--main">
  
    <a href="https://witness.theguardian.com/assignment/5220a453e4b07d9848ba9fdb/522390" itemprop="url"><img src="https://n0tice-static.s3.amazonaws.com/images/reports/microblogs/mediumoriginalaspectdouble/1378473704870db99034baa042d0bce9fe3a71b178bc2.jpg" alt="Waiting For A Haircut " itemprop="contentURL"/></a>
  

  
  <figcaption>
  
    <h3 class="element-witness--title" itemprop="name"><a href="https://witness.theguardian.com/assignment/5220a453e4b07d9848ba9fdb/522390" itemprop="url">Waiting For A Haircut </a></h3>
  
  
  </figcaption>
  
</div>
<footer class="element-witness--footer">
  <p class="element-witness--source">Sent via <a href="https://witness.theguardian.com/" class="element-witness--brand" itemprop="provider">GuardianWitness</a></p>
  <div class="element-witness--metadata">
    <p class="element-witness--author" itemprop="author" itemscope itemtype="http://schema.org/Person">
      
      By
      
      <a href="https://witness.theguardian.com/user/guardianUser12161710" class="element-witness--author-name" itemprop="name">Rob Orton</a>
    </p>
    <p class="element-witness--date">
      <time itemprop="dateCreated" datetime="2013-09-06T13:21:45Z">6 September 2013, 14:21</time>
    </p>
  </div>
</footer>

</figure>

Instagram

<iframe src="//instagram.com/p/c98oOgntiY/embed/" width="612" height="710" frameborder="0" scrolling="no" allowtransparency="true"></iframe>

Flickr

<a href="http://www.flickr.com/photos/66829629@N02/9387471519/" title="Untitled by jakepler1, on Flickr"><img src="http://farm4.staticflickr.com/3709/9387471519_44985df7ee.jpg" width="500" height="500" alt="Untitled"></a>

Facebook

<div id="fb-root"></div> <script>(function(d, s, id) { var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) return; js = d.createElement(s); js.id = id; js.src = "//connect.facebook.net/en_US/all.js#xfbml=1"; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'facebook-jssdk'));</script>
<div class="fb-post" data-href="https://www.facebook.com/vadim/posts/10103462953635090"></div>

Google+

<!-- Place this tag in your head or just before your close body tag. -->
<script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>

<!-- Place this tag where you want the widget to render. -->
<div class="g-post" data-href="https://plus.google.com/110911561642285241845/posts/EekhQ7ununs"></div>

Guardian interactive

    <figure class="interactive" data-interactive="http://path/to/interactive/boot.js">
        <table>
            <tr>
                <td>North Circular</td>
                <td>346</td>
                <td>12%</td>
            </tr>
            ...
        </table>
        <caption>
            This is a chart describing the most polluted roads in London. 
        </caption>
    </figure>

See spec

Document cloud

<div id="DC-note-60903" class="DC-note-container"></div>
<script src="http://s3.documentcloud.org/notes/loader.js"></script>
<script>
  dc.embed.loadNote('http://www.documentcloud.org/documents/371660/annotations/60903.js');
</script>

Streaming services

e.g. Brightcove player

<!-- Start of Brightcove Player -->

<div style="display:none">

</div>

<!--
By use of this code snippet, I agree to the Brightcove Publisher T and C
found at https://accounts.brightcove.com/en/terms-and-conditions/.
-->

<script language="JavaScript" type="text/javascript"
src="http://admin.brightcove.com/js/BrightcoveExperiences.js"></script>

<object id="myExperience2287690716001" class="BrightcoveExperience">
  <param name="bgcolor" value="#FFFFFF" />
  <param name="width" value="740" />
  <param name="height" value="432" />
  <param name="playerID" value="2236101142001" />
  <param name="playerKey"
value="AQ~~,AAAB9FzAoQE~,N298q3_U8K7xy-MTZ9RJjmPgNFzzwACi" />
  <param name="isVid" value="true" />
  <param name="isUI" value="true" />
  <param name="dynamicStreaming" value="true" />

  <param name="@videoPlayer" value="2287690716001" />
</object>

<!--
This script tag will cause the Brightcove Players defined above it to
be created as soon
as the line is read by the browser. If you wish to have the player
instantiated only after
the rest of the HTML is processed and the page load is complete,
remove the line.
-->
<script type="text/javascript">brightcove.createExperiences();</script>

<!-- End of Brightcove Player -->

Legacy JS (document.write)

<script>
document.write("<script src='http://example.com/something.js'></script>");
</script>

References

  • Fence - Code sandboxing micro-library using <iframe srcdoc="..."> (polyfill)
  • Caja - Richer tool for safe embedding
  • Embed responsively - Extend popular embed code to make them responsive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment