Magnolia React Editor
This page describes the installation, components and functions of the Magnolia React Editor — a lightweight, fully-featured library connecting React projects with the WYSIWYG authoring experience of the Magnolia Pages app.
Installation
To install the editor, open the command prompt and enter the following command.
npm install @magnolia/react-editor
is the latest version of the Magnolia React Editor. |
Reference
<EditableArea>
The wrapping component for areas.
The component can be used only inside the React components that are instantiated by EditablePage
. That is, the React component must be in the componentMappings
object supplied to the EditablePage
via its config
parameter.
By default, the area component loops over all of its child components.
EditableArea
renders React components for each component node in its content
. It determines which component to render based on the mgnl:template
value of the node and the componentMappings
supplied to the EditablePage config
property. The properties of each component and areas (if any) are passed as props to the child components.
The default behavior can be changed with customView
.
In the editor view of the Magnolia Pages app, it will add the annotations that are required to render the green bars with the authoring UI. The annotations are added as HTML comments.
Properties
Property | Description |
---|---|
|
Area content that is passed as a property to the parent component where the
|
|
Required only when using
|
|
|
|
Used to add CSS classes to EditableArea wrapping element.
|
|
Function to overwrite the default behavior of the
|
<EditableComponent>
The wrapping component for components.
EditableComponent
component can only be used inside the customView
of the EditableArea
.
The component determines which React component to render based on the mgnl:template
value of the content
and the componentMappings
supplied to the EditablePage config
property. Component dialog properties and areas are passed to the component as props.
<EditablePage>
The wrapping component for Magnolia-managed page content.
It determines which React component to render based on the mgnl:template
value of the content
and the componentMappings
supplied to the EditablePage config
property. Page dialog properties and areas are passed to the component as props.
In the editor view of the Pages app, it will add the annotations that are required to render the green bars with the authoring UI. The annotations are added as HTML comments.
Properties
Property | Description | ||
---|---|---|---|
|
Page content response coming from Magnolia Delivery API.
An example response can be seen here. |
||
|
Configuration object containing the
|
||
or
|
Template information required for the Page Editor to create the authoring UI (the green bars).
|
Example
import React from 'react';
import ReactDOM from 'react-dom';
import { EditablePage, EditorContextHelper } from '@magnolia/react-editor';
import Home from './pages/Home';
const config = {
componentMappings: {
'spa:pages/Home': Home,
},
};
class App extends React.Component {
state = {};
async componentDidMount() {
let templateAnnotations;
const pageRes = await fetch('http://localhost:8080/.rest/pages/spa-home');
const page = await pageRes.json();
if (EditorContextHelper.inIframe()) {
const templateAnnotationsRes = await fetch(
'http://localhost:8080/.rest/template-annotations/v1/spa-home'
);
templateAnnotations = await templateAnnotationsRes.json();
}
this.setState({ page, templateAnnotations });
}
render() {
const { page, templateAnnotations } = this.state;
return (
<>
{page && config && <EditablePage content={page} config={config} templateAnnotations={templateAnnotations} />}
</>
);
}
}
ReactDOM.render(
<React.StrictMode>
<App />
</React.StrictMode>,
document.getElementById('root')
);
EditorContextHelper.inIframe
Using EditorContextHelper.getMagnoliaContext is the recommended approach.
global.mgnlInPageEditor is deprecated and not necessary.
|
EditorContextHelper.getMagnoliaContext
A function that returns the magnoliaContext
object.
This function requires 3 parameters:
Property | Type | Description | ||
---|---|---|---|---|
|
string |
A full request/site URL (e.g.,
|
||
|
string |
Magnolia’s root node path of the SPA website e.g. |
||
|
array of strings |
Website language(s) passed as an array of strings (e.g.,
|
magnoliaContext
object
Property | Type | Description | ||
---|---|---|---|---|
|
boolean |
Specifies whether the request comes from Magnolia app e.g. |
||
|
boolean |
Specifies whether the request comes from Magnolia app in edit mode. |
||
|
boolean |
Specifies whether the request comes from Magnolia app in preview mode. |
||
|
string |
The version number.
|
||
|
string |
Magnolia’s node path for requested content. |
||
|
string |
The language for requested content. |
||
|
object |
Object with search parameters of the |
||
|
string |
String with search parameters of the |
Example
import { EditorContextHelper } from '@magnolia/react-editor';
const requestUrl = 'https://foo.bar/travel/?mgnlPreview=false&mgnlChannel=desktop';
const spaRootNodePath = '/home';
const languages = ['en', 'de'];
const magnoliaContext = EditorContextHelper.getMagnoliaContext(requestUrl, spaRootNodePath, languages);
/*
magnoliaContext = {
isMagnolia: true,
isMagnoliaEdit: true,
isMagnoliaPreview: false,
nodePath: /home/travel,
currentLanguage: 'en',
searchParams: { mgnlChannel: 'desktop', mgnlPreview: 'false', variants: 'all' },
search: '?mgnlPreview=false&mgnlChannel=desktop&variants=all&lang=en'
}
*/
// Fetch page content
const pagesRes = await fetch(PAGES_API + magnoliaContext.nodePath + magnoliaContext.search);
// Fetch template annotations
if (magnoliaContext.isMagnolia) {
const templateAnnotationsRes = await fetch(TEMPLATE_ANNOTATIONS_API + magnoliaContext.nodePath);
}
When using this function to determine isMagnolia* properties, such as isMagnolia being true , be sure to add magnoliaContext search parameters to all links, so that it ensures the correct behavior when navigating the website inside Magnolia’s app e.g. Pages app .
|
Demo
For headless SPA demos showcasing the Magnolia React Editor, see minimal-headless-spa-demos
.
Changelog
A list of notable changes for any given version is available on the changelog page.