Embed (v1)

Embed component written in HTL that allows third-party widgets (e.g. chatbots, lead generation forms, social media posts, social pixels, videos etc.) to be added to a page.

Features

• The following input types are supported:
  • URL - an author is able to paste a URL of a widget to embed. URLs are checked against registered processors for a match. The following URL processors are provided:
    • oEmbed - generic oEmbed URL processor with out-of-the-box configurations for Facebook Post, Facebook Video, Flickr, Instagram, SoundCloud, Twitter and YouTube.
    • Pinterest - processes Pinterest URLs.
  • Embeddable - an author is able to select from pre-configured trusted embeddables. Embeddables can be parameterized and may include unsafe tags. A YouTube embeddable is included out-of-the-box.
  • HTML - an author is able to enter free-form HTML. HTML is restricted to safe tags only.
• Each input type can be disabled by a template author.
• For the embeddable type, the embeddables that are allowed to be selected in the edit dialog can be configured by a template author.

Component Policy Configuration Properties

The following configuration properties are used:

1. ./urlDisabled - defines whether or not URL input is disabled in the edit dialog.
2. ./embeddablesDisabled - defines whether or not embeddables are disabled in the edit dialog.
3. ./htmlDisabled - defines whether or not free-form HTML input is disabled in the edit dialog.
4. ./allowedEmbeddables - defines the embeddables that are allowed to be selected by an author when embeddables are not disabled.

In addition once the YouTube embeddable is allowed a tab from YouTube component's design dialog is included.

Edit Dialog Properties

The following JCR properties are used:

1. ./type - defines the input type to use. Types include URL, embeddable and HTML.
2. ./url - defines the URL of the widget to embed.
3. ./embeddableResourceType - defines the resource type of an embeddable.
4. ./html - defines a HTML string to embed.
5. ./id - defines the component HTML ID attribute.

BEM Description

BLOCK cmp-embed

Extending the Embed Component

Please read the Security Recommendations before defining an extension.

Extension of the Embed component is possible by providing any of the following:

Custom URL Processor

By implementing the UrlProcessor interface you can create your own URL processor.

You will also need to create an HTL template file, with the same name as the processor field returned in the Result.

Example:

• Pinterest processor
• Pinterest HTL template

Custom oEmbed Configuration

By adding an OSGi configuration you can embed an URL from an oEmbed provider.

Example:

• YouTube configuration

See also:

• oEmbed specification
• oEmbed providers

Custom embeddable fragment

1. Create a hidden component with a supertype of core/wcm/components/embed/v1/embed/embeddable.

2. Create a rendering HTL script suitable for what your want to render.

3. Create a cq:dialog node with only the configuration options needed for your embeddable.

4. Make sure to have the following properties added to a granite:data node under the cq:dialog node:

   cmp-embed-dialog-edit-embeddableoptions="true"
   cmp-embed-dialog-edit-showhidetargetvalue="<embeddableResourceType>"
   

   where <embeddableResourceType> is the resource type of your custom embeddable. See YouTube embeddable options for an example!

5. The JCR properties for the edit configuration options of an embeddable must be namespaced to prevent clashes.

6. (Optional) Create a cq:design_dialog node if the custom embeddable should also extend the content policy configuration for the embeddable. Make sure to also add the properties which are required for the edit dialog. See step 4 and YouTube embeddable options for an example!

Example:

• YouTube embeddable

Security Recommendations

• Only implement URL processors and embeddables for trusted sources, as the payload returned by an endpoint may contain JavaScript.
• Always fetch resources over HTTPS, without sslRelax set to true.
• Do not use the unsafe HTL display context unless the payload is trusted.

Information

• Vendor: Adobe
• Version: v1
• Compatibility: AEM 6.3
• Status: production-ready
• Documentation: https://www.adobe.com/go/aem_cmp_embed_v1
• Component Library: https://www.adobe.com/go/aem_cmp_library_embed
• Author: Vivekanand Mishra
• Co-authors: Jean-Christophe Kautzmann, Richard Hand, Vlad Bailescu

If you were involved in the authoring of this component and are not credited above, please reach out to us on GitHub.