When to Use
Responsive Aspect Ratio
Embeds use an intrinsic 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.
Fomantic'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
| Network | Embed Size |
|---|---|
| Google Maps | 237kb |
| YouTube | 380kb |
| Vimeo | 81kb |
Types
Variations
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 : 'https://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 : 'https://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 | false | Provides ancillary debug output to console |