Version: next

Adding Embed Fields

Embed fields allows you to add a valid oEmbed URL, like YouTube, Vimeo, or Spotify, to generate embedded HTML content, or add your own custom embed content. This guide explains how the default implementation work and how to customize it.

In Front-Commerce we expose the embed fields in two ways;

Standalone Embed fields with an EmbedTransformer
Embed Fields in Wysiwyg with PrismicWysiwyg

In this section we will cover how to implement both of these methods, and how to implement your own custom embed fields.

note

You can read more about the oEmbed format and view a list of supported providers on the oEmbed website.

Standalone Embed Fields

You can learn how to configure an embed field in the prismic documentation.

For this example let's say we want to create an album cover from an embed field.

Adding an Embed Field in your GraphQL Module

First add an embed field in your schema using the oEmbedContent type, for example:

type MyAlbum {
  title: String
  cover: oEmbedContent
}

Then you can add the EmbedTransformer to your album definition which will parse the embed response from Prismic as a rich oEmbedContent type.

my-extension/graphql/album/runtime.js
import { type PrismicLoaders } from "@front-commerce/prismic/graphql";
import { createGraphQLRuntime } from "@front-commerce/core/graphql";

export default createGraphQLRuntime({
  contextEnhancer: ({ loaders }: { loaders: PrismicLoaders }) => {
    const { TitleTransformer } = loaders.Prismic.transformers;
    const { TitleTransformer, EmbedTransformer } = loaders.Prismic.transformers;

    loaders.Prismic.defineContentTransformers("album", {
        fieldTransformers: {
          title: new TitleTransformer()
          cover: new EmbedTransformer(),
        },
      });

    return {};
  }
})

Adding an Embed Field on your Client Side

We have added a PrismicEmbed component to handle the embed response in you client side.

To simplify the usage between the component and the backend data we created a PrismicEmbedFragment which contains the minimum required data for the component, for example:

#import "theme/modules/Prismic/PrismicEmbed/PrismicEmbedFragment.gql"

fragment AlbumFragment on Album {
  title
  cover {
    ...PrismicEmbedFragment
  }
}

The fragment will expose several fields from the oEmbedContent type.

my-extension/theme/modules/Prismic/PrismicEmbed/Embed/Album.tsx
import type { Album as AlbumProps } from "~/graphql/graphql";

const Album = (props: AlbumProps) => {
  return <div>/* Custom Embed Logic */</div>;
};

You can override the default components for each embed type in your own theme

Type	Component
`photo`	`theme/modules/Prismic/PrismicEmbed/Embed/Photo.jsx`
`video`	`theme/modules/Prismic/PrismicEmbed/Embed/Video.jsx`
`link`	`theme/modules/Prismic/PrismicEmbed/Embed/Link.jsx`
`rich`	`theme/modules/Prismic/PrismicEmbed/Embed/Rich.jsx`

As mentioned above, the fragment only exposes the minimum required fields for the PrismicEmbed component, if you would like to create your own custom embed component you can refer to all the available fields on the oEmbedContent type.

Wysiwyg Embed Fields

Using the `PrismicWysiwyg` type

Update your schema to use the PrismicWysiwyg type instead of the DefaultWysiwyg.

type MyAlbum {
  title: String
  cover: oEmbedContent
  content: DefaultWysiwyg
  content: PrismicWysiwyg
}

Then use the RichtextToWysiwygTransformer which will transform the Prismic Richtext to the Wysiwyg format.

my-extension/graphql/album/runtime.js
import { type PrismicLoaders } from "@front-commerce/prismic/graphql";
import { createGraphQLRuntime } from "@front-commerce/core/graphql";

export default createGraphQLRuntime({
  contextEnhancer: ({ loaders }: { loaders: PrismicLoaders }) => {
    const { TitleTransformer, EmbedTransformer } = loaders.Prismic.transformers;
    const { TitleTransformer, EmbedTransformer, RichtextToWysiwygTransformer } = loaders.Prismic.transformers;

    loaders.Prismic.defineContentTransformers("album", {
        fieldTransformers: {
          title: new TitleTransformer()
          cover: new EmbedTransformer(),
          content: new RichtextToWysiwygTransformer(loaders.Wysiwyg),
        },
      });

    return {};
  }
})

Adding additional Embed loading scripts

We have added default loading scripts for the following embeds:

Twitter
Facebook
Instagram

You can add your own by overriding the theme/modules/Wysiwyg/PrismicWysiwyg/Components/EmbedScript/appEmbeds.js file.

This file accepts a record with the key as the embed provider (case sensitive).
The value contains a load function and optionally an src if you would like to use a custom script.

theme/modules/Wysiwyg/PrismicWysiwyg/Components/EmbedScript/appEmbeds.js
const appEmbeds = {
  // Add you custom embed script here eg:
  Facebook: {
    // this will override the `Facebook` script included by Front-Commerce
    src: "https://example.com/my-custom-facebook-script.js", // optional src (it's not recommended to change this)
    load: (ref) => {
      // this is only triggered once the script load event is fired
      if (typeof window !== "undefined" && window.FB) {
        window.FB.XFBML.parse(ref);
      }
    },
  },
};

export default appEmbeds;

Custom HTML and Raw Embed Fields

To add Custom HTML or Raw Embed Fields you would need to make some customization to the PrismicWysiwyg component.

Setup your Prismic Rich text

You need to setup your Prismic Rich text field to allow the pre tag in your Prismic dashboard.

Create your custom component

This component will be used to inject the html from the pre tag into the dom.

theme/modules/Wysiwyg/PrismicWysiwyg/Components/Pre.jsx
const Pre = (props) => {
  const html = props.children[0].props.children || "";
  return html ? <div dangerouslySetInnerHTML={{ __html: html }} /> : null;
};

export default Pre;

To improve the loading of scripts you can implement your own useEffect to lazy load the specific script by detecting the provider in the HTML raw text, you might also be interested in implementing a helper like dangerously-set-html-content which can better handle to loading of injected scripts.

Register your custom component

You can register the component by overriding the theme/modules/Wysiwyg/PrismicWysiwyg/appComponentsMap.js file.

theme/modules/Wysiwyg/PrismicWysiwyg/appComponentsMap.js
import Pre from "./Components/Pre";

const appComponentsMap = {
  pre: Pre,
};

export default appComponentsMap;

Example of a custom embed

Here is an example of a custom embed field in a Prismic document.

<blockquote class="twitter-tweet">
  <p lang="en" dir="ltr">
    Front-Commerce 3.9 &amp; 2.34 are here, wrapping up the year with exciting
    updates! 🎉<br /><br />As the holiday season approaches, we’ve packed this
    release with features designed to enhance project flexibility and
    performance. <br /><br />Find out all about this release ➡️
    <a href="https://t.co/TwLSAIBEpp">https://t.co/TwLSAIBEpp</a>
    <a href="https://t.co/mJlzEHeUfq">pic.twitter.com/mJlzEHeUfq</a>
  </p>
  &mdash; Front-Commerce (@Front_Commerce)
  <a
    href="https://twitter.com/Front_Commerce/status/1859991771360764305?ref_src=twsrc%5Etfw"
    >November 22, 2024</a
  >
</blockquote>
<script
  async
  src="https://platform.twitter.com/widgets.js"
  charset="utf-8"
></script>

Here is a preview of how the content will look in the rendered Wysiwyg component.

tip

This can also be done in slices, see the Add Custom Embed or HTML code article for more information.

Standalone Embed Fields​

Wysiwyg Embed Fields​

Custom HTML and Raw Embed Fields​

Standalone Embed Fields

Wysiwyg Embed Fields

Custom HTML and Raw Embed Fields