Integrate Ceros experiences with Drupal 8

I worked on a project recently where the client had some interactive pages created in Ceros. They call them "Experiences", so we'll just stick to that naming for Ceros content. Take a look at their examples for some of the cool interactions you can get. It kinda reminds me of the Flash days, except this is HTML5, so it's better :)

The default way to have the Ceros experiences appear on your website is to use their embed code, which consists of a wrapper div with a bunch of inline styles and attributes, an iframe, and a Javascript file import. As long as your page doesn't do anything to mess with the dimensions of the wrapper div and iframe, it should just work.

Here's an example embed code (I've formatted it so it's easier to read - it's usually one long line):

<div 
  style='
    position: relative;
    width: auto;
    padding: 0 0 174.84%;
    height: 0;
    top: 0;
    left: 0;
    bottom: 0;
    right: 0;
    margin: 0;
    border: 0 none
  ' 
  id="experience-5c93c4d6c1129" 
  data-aspectRatio="0.5719" 
  data-mobile-aspectRatio="0.2716">

  <iframe 
    allowfullscreen 
    src='//view.ceros.com/ceros-educate/adaptive-layouts-build-along-1?heightOverride=2238&mobileHeightOverride=2945' 
    style='
      position: absolute;
      top: 0;
      left: 0;
      bottom: 0;
      right: 0;
      margin: 0;
      padding: 0;
      border: 0 none;
      height: 1px;
      width: 1px;
      min-height: 100%;
      min-width: 100%
    ' 
    frameborder='0' 
    class='ceros-experience' 
    scrolling='no'>
  </iframe>
</div>
<script type="text/javascript" src="//view.ceros.com/scroll-proxy.min.js"></script> 

Note the padding inline style on the wrapper div - the bottom padding amount will vary depending on the aspect ratio and size of the iframe. Without it, your iframe will not be the right size and weird things start to happen with content that should be below the iframe.

A CMS like Drupal is a slightly different beast, though. Sure, you can create a text format that implements no filtering and throw the embed code into a textarea that uses that filter. That will work just fine in many cases e.g. if you're the only one working on your site. But, if you have multiple people adding content to your site, security becomes an issue, and not stripping out potentially bad things - like scripts - is generally not a good idea. You could create a text format that specifically only allows the elements in the embed code, but the Allowed HTML filter will ALWAYS strip out inline styles, so you lose that critical bottom padding.

Turns out, Ceros has an oEmbed option too. Once you have Drupal configured, you simply provide the url to the Ceros experience using the https:\view.ceros.com[account][page-url] format, and it generates the embed code for you. No security issues and nothing important gets stripped out.

How to configure Drupal for oEmbed

1. Install the URL Embed module (will install Embed module too).
2. Go to /admin/config/content/formats and create a new text format for Ceros content. You could also add it to an existing format if you prefer.
3. Enable the filters "Display embedded URLs" and "Convert URLs to URL embeds".
4. Ensure that "Convert URLs to URL embeds" runs before "Display embedded URLs".
5. If the "Limit allowed HTML tags" filter is enabled, add to the Allowed HTML tags.
6. If you have CKEditor enabled for the text format, URL Embed provides a button (it has a music note and a video icon on it) that you can add to your toolbar to make embedding urls easier. It will open up a modal to put your url in, then load it and display it in CKEditor directly.
7. I created a separate field just for Ceros content, but you can easily just embed directly into existing fields via CKEditor. The field is a text (formatted) field and uses the special Ceros text format as the default. Note: I had to put a space in the text field to make it actually keep the Ceros text format as the default format.

That's basically it. If you put a Ceros url into the field and save the node, you should see the spinner from Ceros appear and eventually your content will load. Ensure that you see the bottom padding amount is showing up on the wrapper div and you should be all set.