Popover Options and API
Customize your popover embeds with options, methods, and tips specific to popovers
Wistia's popover embed displays in a lightbox that pops out over the page when opened. This article contains details on options and API functions specific to these lightbox-style embeds.
Popover embeds
The basic structure of a popover embed includes the E-v1.js script, a wistia_embed container, and the popover=true embed option.
<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_gbe33h571z popover=true" style="display:inline-block;height:360px;position:relative;width:640px"> </span>
That is, they are very similar in structure Standard Inline Embeds, but with the option popover=true and the container is a <span> element instead of a <div>.
Using popover embed options
Just like adding options to a standard embed, popover embed options are added into the class="wistia_embed" attribute, right after popover=true, inside of the quotations. For example, if I wanted a thin border on my popovers, I'd add the popoverBorderWidth=2 option like this:
<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_gbe33h571z popover=true popoverBorderWidth=2" style="display:inline-block;height:360px;position:relative;width:640px"> </span>
You can set any of the options listed below in exactly the same way, as well as most of the non-popover embed options.
Popover embed options
For a list of all generic options, refer to the Embed Options documentation. The options listed here are the ones specific to popovers or with special popover behavior.
popoverDisableAutoPlay
The popoverDisableAutoPlay option allows you to override the autoplay behavior for popover embeds. Set to popoverDisableAutoPlay=true so that launching the popover doesn't also play the video–it will require an additional click. You will see the thumbnail of the video when you click the initial thumbnail display for the popover.
popover=true
The popover option is important, but the value should always be the same. Setting the popover=true will tell the embed code that it should behave like a popover.
popoverShowOnLoad
Set this to true and the popover will immediately open the video as if it was clicked. This may be useful for landing pages where you want the video to be front and center but don't otherwise have the space.
playButton
If popoverContent is set to "thumbnail", then playButton determines whether the big play button shows up over the thumbnail.
This option also controls whether the big play button will show up over the video when the video loads, though it is usually not relevant to popovers in that form since they autoplay.
popoverContent
When popoverContent is not set or explicitly set to "thumbnail", the video thumbnail will be rendered in the container, cropped to fit with no black bars.
<script src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverContent=thumbnail" style="width:300px;height:150px;"> </span>
When popoverContent is set to "html", the HTML inside the container is not modified, with the exception of being wrapped in the wistia_13.thumb_container div. Clicking inside this container will launch the popover video.
<script src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverContent=html" style="display:inline-block; white-space:nowrap;" id="wistia-5bbw8l7kl5-1">
<div id="wistia_13.thumb_container" style="position: relative; height: 18px; width: 34px;">
<div>
<span>Launch the popover!</span>
</div>
</div>
</span>
Note that you do not need to use an <a> tag inside the popover, but it is used here because it conveniently uses native link styles.
Here's a similar version where a custom image is also defined:
<script src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverContent=html" style="display:inline-block; white-space:nowrap;">
<a href="#">
<img src="https://yoursite.com/custom-image.jpg/">
</a>
</span>
Prevent Thumbnails Loading for popoverContent=link
Using a link-based popover will still load in a thumbnail from Wistia, adding to the page load. To prevent this from happening, implement the stillUrl Embed Option with a custom image or meaningless string.
Tip
The
stillUrlembed option expects the value to be a string. Using an integer value such asstillUrl=1will cause errors in the browser. Instead, use a letter e.g.stillUrl=a, or the provided image URL below.
We recommend using this image URL which is a tiny, base64-encoded, fully tansparent .png image:
stillUrl=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=
Here's an example of that in action:
<script src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverContent=link stillUrl=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
style="display:inline-block; white-space:nowrap;">
<a href="#">This is my popover!</a></span>
</span>
popoverOverlayColor
Use this to change the overlay's background color in RGB hexadecimal. By default this is set to "000000". To change it to white, use "ffffff".
<script src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverOverlayColor=ffffff" style="width:300px;height:150px;"> </span>
popoverOverlayOpacity
Use this to change the overlay's opacity. This expects a decimal value between 0 and 1. The default value is 0.5.
<script src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverOverlayOpacity=0.8" style="width:300px;height:150px;"> </span>
popoverAnimateThumbnail
Set this to true if you want the play button to expand to cover the thumbnail on hover, while also displaying the duration of the video. Set to false if you want no special behavior on hover. If not specified, the default is false, though this option is explicitly set to true by default in the embed codes you'll get from the Wistia App UI.
popoverAnimation
Currently popovers have a few different launch animations. Possible values are:
- none: Shows the popover with no animation and no delay.
- fade: Fades in the popover along with the overlay.
- slide: Fades in the overlay and slides/fades the video up into place.
The default is "slide", though because of graphics card interaction issues, it will default to "fade" if the video uses the Flash player.
popoverPreventScroll
By default, popovers render an overlay covering the entire document. But they do not stop the user from scrolling the content behind the video. Set this to true if you would like to prevent the user from scrolling content.
Note: It accomplishes this by setting height:100%;overflow:hidden CSS properties on the <body> element. If you have a custom scrolling implementation, this will not prevent scrolling in it. To implement a custom solution, you may want to bind to the "popovershow" and "popoverhide" events.
popoverSize
By default, popover videos will automatically take over most of the browser window, leaving a comfortable space between the video and the edge of the window on all sides.If you would instead prefer to define specific dimensions for the video, you can set popoverSize to widthxheight. For example, to make the popover video display at 640px by 360px, you would use popoverSize=640x360.
Note: If the specified dimensions would be too large to display on the viewer's screen, the video will instead revert to the responsive default.
popoverBorderWidth
Popovers have no borders by default. Use this option to add a border around the video. It expects the width to be an integer defined in pixels.
popoverBorderColor
Use this option to change the popover border color. By default this is set to "ffffff". To change it to black, use "000000".
popoverBorderRadius
Popovers have 0 border radius by default. If your website uses round borders, use this option to set a matching border radius. It expects a value in pixels.
popoverBoxShadow
Popovers have a diffuse box shadow by default. If you don't want any box shadow, set this option to false.
popoverCaption
Use this option to add some short text directly below the video. If there are spaces, the value must be percent-encoded, which you can do with the browser's encodeURIComponent function.
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverCaption=This%20is%20a%20caption." style="width:300px;height:150px;"> </div>
popoverCaptionContainer
If you need longer text or more complex behavior and styling, use this option instead of popoverCaption. With popoverCaptionContainer, you specify the ID of a DOM element that should be shown below the caption. This DOM element will be moved (not cloned) and displayed when the popover is launched, so any bindings or styles that target it will stay in tact.
<script src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_5bbw8l7kl5 popover=true popoverCaptionContainer=caption_content1" style="width:300px;height:150px;"> </span>
<div id="caption_content1" style="display:none;">
I can have *complex markup* here, <a href="#" onclick="alert('hi!'); return false;">setup bindings</a>, or even define other embed codes to accompany it.
</div>
Popover methods
For a list of all methods, refer to the Player API. The methods listed here are the ones specific to popovers. Popover methods are defined in the popover namespace of each player API handle.
height()
Returns the current height of the popover container (usually the thumbnail) in pixels.
// e.g. set the height of <div id="next_to_video"> to match the video.
$("#next_to_video").height(video.popover.height());
height(val, [options])
Sets the height of the popover container to val in pixels. It is expected that val is an integer. Decimal or string values will be truncated.
If constrain: true is passed as an option, then the width of the container will also be updated to maintain the correct aspect ratio.
video.popover.height(100);
video.popover.height(150, { constrain: true });
hide()
If the popover is open, this will hide it.
video.popover.hide()
show()
If the popover is hidden, this will show it.
video.popover.show()
width()
Returns the current width of the popover container (usually the thumbnail) in pixels.
// e.g. set the width of <div id="next_to_video"> to match the video.
$("#next_to_video").width(video.popover.width());
width(val, [options])
Sets the width of the popover container to val in pixels. It is expected that val is an integer. Decimal or string values will be truncated.
If constrain: true is passed as an option, then the height of the container will also be updated to maintain the correct aspect ratio.
video.popover.width(100);
video.popover.width(150, { constrain: true });
Popover Events
For a list of all generic events, refer to the Player API. The events listed here are the ones specific to popovers.
popovershow
Fired when the popover becomes visible.
video.bind("popovershow", function() {
console.log("The popover for ", video.hashedId(), " is visible!");
});
popoverhide
Fired when the popover is hidden.
video.bind("popoverhide", function() {
console.log("The popover for ", video.hashedId(), " is hidden!");
});
Popover tips and examples
Open popover embeds from a custom button or element
Should you want a more flexible approach to opening a popover embed, it's possible to use a custom button or other element to launch the popover player.
Simple custom popover button
Glitch
See this example in action - simple custom popover button
The simplest way to create a custom button or element for your popover starts with text link popover embed, like this one:
<script src="https://fast.wistia.com/embed/medias/0q4budn88u.jsonp" async></script>
<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_0q4budn88u popover=true popoverContent=link" style="display:inline;position:relative">
<a href="#">This is my popover!</a></span>
The anchor element, <a href="#">, inside of the class="wistia_embed" container, opens the popover. So you can replace link text This is my popover! text with a button , img or other desired element!
<script src="https://fast.wistia.com/embed/medias/0q4budn88u.jsonp" async></script>
<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_0q4budn88u popover=true popoverContent=link" style="display:inline;position:relative">
<a href="#"><button type="button">Click Me!</button></a></span>
Custom popover button using embed links
Glitch
See this example in action - popover button with embed links
If you need the popover to open from a custom button but are unable to place the button inside of the wistia_embed container, for example when embedding within a specific theme or template, you can use Wistia's embed links to get around this limitation. Similar to the example above, we'll first embed a text link popover on the page, and simply remove the link inside of the span element:
<script src="https://fast.wistia.com/embed/medias/0q4budn88u.jsonp" async></script>
<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>
<span class="wistia_embed wistia_async_0q4budn88u popover=true popoverContent=link" style="display:inline;position:relative"></span>
This will embed the video, but keep it hidden until the button is clicked. Next, we'll construct an embed link that points to the hashed_id of our video:
#wistia_0q4budn88u
The final step is to make sure that the button links to #wistia_0q4budn88u. If the video is successfully embedded on the page and the hashed_id of the embed link matches the embed code, this should open the popover when clicked.
Updated 4 days ago