Display WYSIWYG content
WYSIWYG stands for What You See Is What You Get. It means that your back office users write their content without needing any HTML or React knowledge. This is the case in most CMS tools nowadays. The output though is usually HTML which does not necessarily match the React components you’ve built in your Front-Commerce application.
This is why we’ve built a theme/modules/WysiwygV2
component in Front-Commerce. In this guide you will learn how to use it and how to customize its display.
It is namedWysiwygV2
because it has performance improvements over the legacytheme/modules/Wysiwyg
. Please refer to the legacy documentation page for more information about the old behavior.
Note: The WysiwygV2 is not used in the default theme yet because of backward compatibility issues. It will arrive in a future release, but you can already use it today in your own theme by overriding the components that should use it.
<WysiwygV2 />
usage
Here is an example of using this component:
import React from "react";
import WysiwygV2 from "theme/modules/WysiwygV2";
export default (props) => <WysiwygV2 content={props.cms.contentWysiwyg} />;
The contentWysiwyg
property must come from a GraphQL field of type Wysiwyg
, you should add the WysiwygFragment
available at theme/modules/WysiwygV2/WysiwygFragment.gql
, to the CmsPageFragment
available at theme/pages/CmsPage/CmsPageFragment.gql
.
#import "theme/modules/CmsPage/CmsPageSeo/CmsPageSeoFragment.gql"
+ #import "theme/modules/WysiwygV2/WysiwygFragment.gql"
fragment CmsPageFragment on CmsPage {
identifier
title
- content
+ contentWysiwyg {
+ ...WysiwygFragment
+ }
content_heading
...CmsPageSeoFragment
}
What if the Wysiwyg
field does not exist in your schema?
In some cases, you won’t have an already parsed Wysiwyg field in your GraphQL schema. You will need to add it yourself. First, you will need to create your own GraphQL module in which you will add a new GraphQL field and the associated resolver. Please refer to Extend the GraphQL schema for detailed instruction.
How does this translate to our Wysiwyg case? Let’s imagine that we are adding a contentWysiwyg
to a CmsPage
GraphQL type. Then this means that we will have to do the three following steps:
- Add
Front-Commerce/Wysiwyg
as a dependency to your GraphQL module
// my-module/server/modules/wysiwyg/index.js
export default {
namespace: "Magento2/Cms",
+ dependencies: [
+ "Front-Commerce/Wysiwyg"
+ ],
- Add the new Wysiwyg field to the type you want to extend
# my-module/server/modules/wysiwyg/schema.gql
extend type CmsPage {
contentWysiwyg: Wysiwyg
}
- Set the resolver for the newly created field to parse the Wysiwyg content
// my-module/server/modules/wysiwyg/resolvers.js
export default {
+ CmsPage: {
+ contentWysiwyg: (cmsPage, _, { loaders }) => {
+ // The content is the raw HTML string returned by your remote service
+ const rawContent = cmsPage.content;
+
+ // The type specifies how to transform the content
+ // For instance Magento has a specifc {{ widget }} syntax
+ // By using the `MagentoWysiwyg` type, we tell the loader
+ // to apply the correct transformations for Magento related
+ // strings
+ const contentType = "MagentoWysiwyg"
+
+ // We then parse it and fetch the data needed to display it
+ return loaders.Wysiwyg.parse(content, "MagentoWysiwyg");
+ }
+ }
}
WysiwygV2 customization
Prerequisite: Please note that the following sections use advanced techniques in Front-Commerce. You especially need to be familiar with the GraphQL extension mechanisms before being able to fully apprehend what is explained. If some areas are still unclear, please feel free to reach out!
Create a new Wysiwyg Type
Each service is likely to have their own set of rules and constraints when it comes to Wysiwyg. For instance, in Magento you have shortcodes that are defined by using the {{ }}
syntax. In WordPress, you will have []
instead. Despite this syntax difference you will have also some functionality difference. For instance, Magento allows you to display a link to a product while WordPress have media galleries. This means that each service will have its own set of transformations for WYSIWYG data.
We are solving this by creating a new Wysiwyg Type for each service. In the previous section, we’ve mentioned the type MagentoWysiwyg
. It uses the exact same mechanisms as the one we will describe below.
If you want to customize MagentoWysiwyg
instead, please refer to the next section.
Steps to create a new Wysiwyg Type (CustomWysiwyg
)
Register your widget type at the GraphQL level (server-side)
- Add
Front-Commerce/Wysiwyg
as a dependency of your GraphQL module (for instance atmy-module/server/modules/wysiwyg/
) Define a new GraphQL type that should implement the
Wysiwyg
interface# my-module/server/modules/wysiwyg/schema.gql type CustomWysiwyg implements Wysiwyg { raw: String childNodes: JSON data: [WysiwygNodeData] }
Register this new type as a Wysiwyg type in your GraphQL module
// my-module/server/modules/wysiwyg/index.js contextEnhancer: ({ loaders }) => { loaders.Wysiwyg.registerWysiwygType( // the name of the GraphQL type you have just created "CustomWysiwyg", // The list of shortcodes that are parsed and replaced in your wysiwyg content [ { // regex to identify the shortcode within your HTML code regex: /\{\{media url="(.*?)"\}\}/gi, // How to replace the given shortcode replacement: (match, url) => `/media/${url}`, }, ] ); };
Map this new type to a specific React component that will apply the needed transformations before displaying the content (client-side)
- Duplicate
theme/modules/WysiwygV2/DefaultWysiwyg
totheme/modules/WysiwygV2/CustomWysiwyg
. - Override
theme/modules/WysiwygV2/getWysiwygComponent.js
and map your newCustomWysiwyg
typename (the one used in your GraphQL schema) totheme/modules/WysiwygV2/CustomWysiwyg
(the file that tells React how to display the content)const typenameMap = { - MagentoWysiwyg: loadable(() => import("./MagentoWysiwyg/MagentoWysiwyg")) + MagentoWysiwyg: loadable(() => import("./MagentoWysiwyg/MagentoWysiwyg")), + CustomWysiwyg: loadable(() => import("./CustomWysiwyg")) };
This is it, you have a new CustomWysiwyg
type. However, the components rendered are still simple HTML tags. If you want to add interactivity, you will need to refer to the theme/modules/WysiwygV2/CustomWysiwyg
you have created.
In this file you will notice that there is a defaultComponentsMap
constant. This object is used to reference how to render each html tag in your Wysiwyg component. We call these transforms: they transform an html tag into a React component. This is what will allow you to finely tune how your Wysiwyg is displayed and add interactivity to your content.
For instance, if you want your h2
tags to have some additional classes, you could use the following defaultComponentsMap
instead:
const defaultComponentsMap = {
h2: (props) => <h2 {...props} className="wysiwyg-h2" />,
};
The props available represent the HTML attributes coming from your Wysiwyg content. The only difference compared to traditional HTML is that class
is renamed to className
to better support React patterns and the props.children
is an already constructed React element.
Note: If the component is complex, please think about code splitting them to avoid too large bundles on pages that don’t need them.
Fetching data to render Wysiwyg components
You can now transform HTML tags into React components. However, in some cases the data provided in the raw HTML you’ve received from your remote service won’t be enough to display your component. For instance, you may have a <product-name sku="VSK12" />
that is supposed to display the product’s name. But all you have in the attributes is the SKU. This can be done by associating a WysiwygNodeData
with your HTML node.
Indeed, when you’ve created your GraphQL CustomWysiwyg
type, you have declared: childNodes
(JSON
) and data
([WysiwygNodeData]
). By default, data
will always be empty. But you can tell the Wysiwyg loader to fetch data for some specific childNodes
(that each represent an HTML tag). This means that for product-name
, you will associate a new data
element that will contain the whole product data needed to display the component. To do so, you need to follow these steps:
Add the product data to your GraphQL schema (server-side)
Make sure that your dependencies are up to date in your GraphQL module
// my-module/server/modules/wysiwyg/index.js export default { namespace: "Magento1/Cms", + dependencies: [ + "Front-Commerce/Wysiwyg", // to make sure that Wysiwyg related features are available + "Magento2/Catalog/Product" // to make sure that you can fetch a product in your Wysiwyg data + ],
Define a new
WysiwygProductNameData
type that implementsWysiwygNodeData
and expose all the data you need to display your component# my-module/server/modules/wysiwyg/schema.gql type WysiwygProductNameData implements WysiwygNodeData { dataId: ID product: Product }
Setup the resolvers to tell GraphQL how to fetch the
product
field in your newWysiwygProductNameData
type// my-module/server/modules/wysiwyg/resolvers.js export default { + WysiwygProductNameData: { + product: ({ node }, _, { loaders }) => { + const productSkuAttribute = node.attrs.find(({ name }) => name === "sku") + if (!productSkuAttribute) { + return null; + } + return loaders.Product.load(productSkuAttribute.value) + } + }, }
Register the HTML tag and associate it with the GraphQL type
// my-module/server/modules/wysiwyg/index.js contextEnhancer: ({ loaders }) => { + loaders.Wysiwyg.registerNodeType( + "product-name", // the tag name in your HTML + "WysiwygProductNameData" // The associated GraphQL type name + ); }
Fetch the data to make it available in your custom Product Name component (client-side)
-
Override the
theme/modules/WysiwygV2/WysiwygFragment.gql
to fetch the newWysiwygProductNameData
Feel free to split this in a Fragment dedicated to your#import "./MagentoWysiwyg/MagentoWysiwygFragment.gql" fragment WysiwygFragment on Wysiwyg { childNodes data { dataId + ... on WysiwygProductNameData { + product { + sku + name + } + } } ... on MagentoWysiwyg { ...MagentoWysiwygFragment } }
CustomWysiwyg
just like it is done in the core forMagentoWysiwyg
. -
Reference the
product-name
tag in your componentMap and use the newdata
prop available in the mapped component.const defaultComponentsMap = { + product-name: (props) => <span>{props.data.product.name}</span> }
Note: Please keep in mind that for simplicity’s sake, the product name component is not code split, but if it grows in complexity, please make sure to code split it using
@loadable/component
to avoid too large bundles.
Nested Wysiwyg components
In some cases, you will need to render a Wysiwyg component inside another Wysiwyg component. For instance, this can be the case if you implement a Product Preview feature in your Wysiwyg and want to display the description of the product. It is likely to have formatted text that can be defined directly in the administration panel.
Please be advised that we won’t support infinite nested Wysiwyg component since it represents a huge performance risk for both you and your users. The goal would be instead to use only simplified Wysiwyg for nested data. In our Product Preview case, this means that instead of rendering a MagentoWysiwyg
you would only render a DefaultWysiwyg
that won’t fetch additional data but only transform the basic HTML.
If you need more information about implementing this, please contact us.
Dynamic styles
Since version 2.11
You may want to render inline styles dynamically when displaying WYSIWYG components. It can be required if content managers customizes how a given element is displayed for instance (e.g: alignment, border color etc…).
Each <WysiwygV2>
component is wrapped into a unique id. The Front-Commerce WYSIWYG mechanism provides a <Style>
component that allows you to render styles that could be restricted to the current WYSIWYG context only (and prevent side effects on other parts of the page)
Here is how you could use it from a WYSIWYG component:
import React from "react";
+ import Style from "theme/modules/WysiwygV2/Style";
const MyComponent = ({ children, data }) => {
const { id, align, content } = data;
return <>
+ <Style rootSelector="#html-body">{`
+ #html-body [data-my-component-id=${id}] .my-component__content {
+ text-align: "${align}";
+ }
+ `}</Style>;
<div class="my-component" data-my-component-id={id}>
<p class="my-component__introduction">Lorem ipsum…</p>
<p class="my-component__content">{content}</p>
</div>
</>;
};
export default MyComponent;
It will generate an inline <style>
HTML tag with the following content (#html-body
being replaced with the automatically generated wysiwyg element id):
<style>
#wysiwyg-styles-xxxxxxxx-yyyy
[data-my-component-id="42"]
.my-component__content {
text-align: "center";
}
</style>
That’s it!
Everything explained previously is the core behavior of the Wysiwyg implemented in Front-Commerce. It is very flexible as it was implemented over a lot of iterations and feedbacks from our integrators. However, with this flexibility comes a bit of a complexity. Please keep in mind that you don’t need to fully understand all of it to get started. However, if you’ve understood most of it, you will be able to dive into our code and understand how we have implemented platform specific Wysiwyg components. You could even use those components as an inspiration to develop your own specific behaviors.