Embed Component
The Core Components Embed Component allows embedding external content in an AEM content page.
Usage
The Core Component Embed Component allows the content author to define selected external content to be embedded within an AEM content page. In addition, there is an option to define free-form HTML to be embedded as well.
- The component’s properties can be defined in the configure dialog.
- Defaults for the component when adding it to a page can be defined in the design dialog.
Version and Compatibility
The current version of the Embed Component is v2, which was introduced with release 2.18.0 of the Core Components in February 2022, and is described in this document.
The following table details all supported versions of the component, the AEM versions with which the versions of the component is compatible, and links to documentation for previous versions.
For more information about Core Component versions and releases, see the document Core Components Versions.
Sample Component Output
To experience the Embed Component as well as see examples of its configuration options as well as HTML and JSON output, visit the Component Library.
Technical Details
The latest technical documentation about the Embed Component can be found on GitHub.
Further details about developing Core Components can be found in the Core Components developer documentation.
Configure Dialog
The configure dialog allows the content author to define the external resource to be embedded on the page.
Properties Tab
First choose which type of resource should be embedded:
For each type of embeddable, you can define an ID. This option allows to control the unique identifier of the component in the HTML and in the Data Layer.
- If left blank, a unique ID is automatically generated for you and can be found by inspecting the resulting page.
- If an ID is specified, it is the responsibility of the author to make sure that it is unique.
- Changing the ID can have an impact on CSS, JS and Data Layer tracking.
URL
The simplest embed is the URL. Simply paste the URL of the resource you wish to embed in the URL field. The component will attempt to access the resource and if it can be rendered by one of the processors, it will display a confirmation message below the URL field. If not, the field will be marked in error.
The Embed Component ships with processors for the following types of resources:
- Resources that comply with the oEmbed standard including Facebook Post, Instagram, SoundCloud, Twitter, and YouTube
Developers can add additional URL processors by following the developer documentation of the Embed Component.
Embeddable
Embeddables allow for more customization of the embedded resource, which can be parameterized and include additional information. An author is able to select from pre-configured trusted embeddables and the component ships with a YouTube embeddable out-of-the-box.
The Embeddable field defines the type of processor you want to use. In the case of the YouTube embeddable you can then define:
- Video ID - The unique video ID from YouTube of the resource you want to embed
- Width - The width of the embedded video
- Height - The height of the embedded video
- Enable Mute - This parameter specifies whether the video will play muted by default. Enabling this increases the chance that Autoplay works in modern browsers.
- Enable Autoplay - This parameter specifies whether the initial video will automatically start to play when the player loads. This is only effective on the publish instance or when using the View as Published option on the authoring instance.
- Enable Loop - In the case of a single video, this parameter specifies whether the player should repeatedly play the initial video. In the case of a playlist, the player plays the entire playlist and then starts again at the first video.
- Enable Inline Playback (iOS) - This parameter controls whether videos play inline (on) or fullscreen (off) in an HTML5 player on iOS.
- Unrestricted Related Videos - If this option is disabled, related videos will come from the same channel as the video that was just played, otherwise they will come from any channel.
Other embeddables would offer similar fields and can be defined by a developer by following the developer documentation of the Embed Component.
HTML
You can add free-form HTML to your page using the Embed Component.
Security
The HTML markup that the author can enter is filtered for security purposes to avoid cross-site scripting attacks that could for example allow authors to gain administrative rights.
In general, all script and style elements as well as all on* and style attributes will be removed from the output.
However the rules are more complicated because the Embed Component follows AEM’s global HTML AntiSamy sanitation framework filtering rule set, which can be found at /libs/cq/xssprotection/config.xml. This can be overlaid for project-specific configuration by a developer if required.
Additional security information can be found in the AEM developer documentation for on-premise installations as well as AEM as a Cloud Service installations.
/libs/cq/xssprotection/config.xml, these changes affect all HTL and JSP behavior and not just the Embed Core Component.Styles Tab
The Embed Component supports the AEM Style System..
Use the drop-down to select the styles that you want to apply to the component. Selections made in the edit dialog have the same effect as those chosen from the component toolbar.
Styles must be configured for this component in the design dialog in order for the drop down menu to be available.
Design Dialog
The design dialog allows the template author to define the options available to the content author who uses the Embed Component and the defaults set when placing the Embed Component.
Embeddable Types Tab
- Disable URL - Disables the URL option for the content author when selected
- Disable Embeddables - Disables the Embeddable option for the content author when selected, regardless of which embeddable processors are allowed.
- Disable HTML - Disables the HTML option for the content author when selected.
- Allowed Embeddables - Multiselect that defines which embeddable processors are available to the content author, provided that the Embeddable option is active.
YouTube Tab
- Allow configuration of mute behavior - Allows content author to configure the Enable Mute option in the component when the YouTube embed type is selected
- Default value of mute - Automatically sets Enable Mute option when the YouTube embed type is selected
- Allow configuration of autoplay behavior - Allows content author to configure the Enable Autoplay option in the component when the YouTube embed type is selected
- Default value of autoplay - Automatically sets Enable Autoplay option when the YouTube embed type is selected
- Allow configuration of loop behavior - Allows content author to configure the Enable Loop option in the component when the YouTube embed type is selected
- Default value of loop - Automatically sets Enable Loop option when the YouTube embed type is selected
- Allow configuration of inline playback (iOS) - Allows content author to configure the Enable Inline Playback (iOS) option in the component when the YouTube embed type is selected
- Default value of inline playback (iOS) - Automatically sets Enable Inline Playback (iOS) option when the YouTube embed type is selected
- Allow configuration of inline videos - Allows content author to configure the Unrestricted Related Videos option in the component when the YouTube embed type is selected
- Default value of unrestricted related videos - Automatically sets Unrestricted Related Videos option when the YouTube embed type is selected