The salt plugin for Popcorn.js is the backbone of the DataDocs platform. Put simply, salt allows you to control the visibility of HTML divs on a page according to the timestamp of your video.

Though all the code you need is on the github page, this post will offer a quick conceptual overview of what salt does and how.

“Integrating” video and HTML

Data Docs does not actually combine video and interactive HTML elements; it layers those elements over video and then makes them visible only during portions of the video that have been left blank for that purpose.

To allow as much flexibility as possible, Salt requires only three parameters: the id of your target div, a start time (in seconds) and an end time (also in seconds). Once initialized, salt will make all of the divs you’ve told it about invisible, while keeping track of their display type (in order to preserve their positioning on your page). Then, when the video hits the starting timestamp, it makes that div visible. When it reaches the end timestamp, it makes it invisible again. That’s it!

Putting it to use

In practice, the simplest way to work with salt is to create a page with three “container” divs: one to hold the video, one to hold everything you want to have appear over the video, and one that holds both of the previous two. Although none of this is strictly necessary, this will let you move your whole video+HTML package around the page without having to reposition any of your interactive elements, which will save a lot of trouble if your design changes.

If you’re just writing out straight HTML, make sure that your HTML div (and its contents) are on the page after your video div, and that the positioning on both divs is absolute. One thing to be careful of, however, is that the height of your HTML div isn’t more than about 80% of your video’s height – otherwise your HTML content will block the automatic player controls on your video, and you won’t be able to get it to play, pause or anything else. (Fortunately, we soon hope to eliminate this problem with a custom player-control plugin.)

Now just add whatever HTML elements you want to have appear over your video to your HTML container div, positioning them however you like. Any div whose id you pass to the salt plugin will be made invisible as soon as the page is finished loading and then turned on and off again at the timestamps you specify as the video progresses. Best of all you can put anything you like in those divs – from text to images to complex charts. As long as the code is on the page, it will show up.

Not sure where to start?

Want to see how it works? Start by downloading a copy of this page. You’ll also need to download a copy of Popcorn.js (no plugins) and the salt plugin code. Be sure to adjust the paths to these files in the header of your html, and you’ll also need sample video files – if you don’t have any, you can download the Popcorn sample videos (you’ll need all three) here.

If you have any questions, please feel free to use the comments section below!