Menu

Embed
An embed displays content from other websites like YouTube videos or Google Maps

When to Use

Responsive Aspect Ratio

Embeds use an instrinsic aspect ratio which allows them to resize responsively based on their expected aspect ratio and not by using a single specified width or height.

Only Load After Interaction

Including an iframe embed directly will automatically load all iframe contents on page load which can drastically reduce the responsiveness of a page.

Semantic's embed combats this by not loading iframe content until a user has interacted with your embed's placeholder content.

To give you an idea of how much file size including an embed will add to your page load see the chart below

The following are download estimates taken from firebug and a single sample embed. Individual results may vary.
Network Embed Size
Google Maps 237kb
YouTube 380kb
Vimeo 81kb

Types

YouTube

An embed can be used to display YouTube Content

Vimeo

An embed can be used to display Vimeo content.

Custom Content

An embed can display any web content

Embeds use an intrinsic aspect ratios to embed content responsively. Content will preserve their intrinsic aspect ratio for all browser sizes responsively

Variations

Aspect Ratio

An embed can specify an alternative aspect ratio

Initializing

Specifying a URL

Specifying a url will automatically match to an embed source using the domain of the url.

$('.url.example .ui.embed').embed();

Using Content IDs

Embed is designed to automatically generate urls from content ids. This way your site's backend can store meaningful content metadata and not worry about generating urls.

$('.content.example .ui.embed').embed();

Specifying Programmatically

You can also specify embed settings at run-time in the settings object.

$('.custom.example .ui.embed').embed({ source : 'youtube', id : 'O6Xo21L0ybE', placeholder : '/images/bear-waving.jpg' });

Specifying New Sources

Embed comes with two predefined embed sources, but can be extended with custom sources. Each source specifies default parameters and their mappings to settings, a templated url, and what icon should be used for overlays

Extending $.fn.embed.settings.sources allows you to use other proprietary embeds.

// built in $.fn.embed.settings.sources = { youtube: { name : 'youtube', type : 'video', icon : 'video play', domain : 'youtube.com', url : '//www.youtube.com/embed/{id}', parameters: function(settings) { return { autohide : !settings.showUI, autoplay : settings.autoplay, color : settings.colors || undefined, hq : settings.hd, jsapi : settings.api, modestbranding : 1 }; } }, vimeo: { name : 'vimeo', type : 'video', icon : 'video play', domain : 'vimeo.com', url : '//www.youtube.com/embed/{id}', parameters: function(settings) { return { api : settings.api, autoplay : settings.autoplay, byline : settings.showUI, color : settings.colors || undefined, portrait : settings.showUI, title : settings.showUI }; } } };

Behaviors

All the following behaviors can be called using the syntax:

$('.your.element') .embed('behavior name', argumentOne, argumentTwo) ;
Behavior Description
change(source, id, url) Changes iframe to a new content source
reset Removes embed and shows placeholder content if available
show Shows embed content
hide Hides embed content and shows placeholder content
get id Returns current content id
get placeholder Returns placeholder image url
get sources Returns source name
get type Returns source type
get url Returns URL with all parameters added
has placeholder Returns whether embed content has placeholder
destroy Destroys instance and removes all events

Embed Settings
Settings to configure video behavior

Setting Default Description
icon false Specifies an icon to use with placeholder content
source false Specifies a source to use, if no source is provided it will be determined from the domain of a specified url.
url false Specifies a url to use for embed
id false Specifies an id value to replace with the {id} value found in templated urls
parameters false Specify an object containing key/value pairs to add to the iframes GET parameters

Video Settings
Settings to configure video behavior

Setting Default Description
autoplay auto Default setting auto will only autoplay content when a placeholder is specified. Setting to true or false will force autoplay.
color #444444 Specifies a default chrome color with Vimeo or YouTube.
url false Specifies a url to use for embed
hd true Whether to prefer HD content
brandedUI false Whether to show networks branded UI like title cards, or after video calls to action.

Callbacks

Callbacks specify a function to occur after a specific behavior.

Parameters Context Description
onCreate url $module Callback when iframe is generated
onDisplay $module Whenever an iframe contents is shown
onPlaceholderDisplay $module Callback immediately before Embed is removed from DOM
onEmbed parameters $module Callback when module parameters are determined. Allows you to adjust parameters at run time by returning a new parameters object.

DOM Settings
DOM settings specify how this module should interface with the DOM

Setting Default Description
namespace embed Event namespace. Makes sure module teardown does not effect other events attached to an element.
selector
selector : { embed : '.embed', placeholder : '.placeholder', play : '.play' }
DOM Selectors used internally
metadata
metadata : { id : 'id', icon : 'icon', placeholder : 'placeholder', source : 'source', url : 'url' }
HTML Data attributes used to store data
className
className : { active : 'active', embed : 'embed' }
Class names used to attach style to state
templates
$.fn.embed.settings.templates = { iframe: function(url, parameters) { // returns html for iframe }, placeholder: function(image, icon) { // returns html for placeholder element } }
metadata
metadata : { id : 'id', icon : 'icon', placeholder : 'placeholder', source : 'source', url : 'url' }
errors
error : { noURL : 'No URL specified', method : 'The method you called is not defined' }

Debug Settings
Debug settings controls debug output to the console

Setting Default Description
name Embed Name used in debug logs
silent False Silences all console output including error messages, regardless of other debug settings.
debug False Provides standard debug output to console
performance True Provides standard debug output to console
verbose True Provides ancillary debug output to console

Dimmer Message
Dimmer sub-header