Magnolia Angular Editor
This page describes the installation, components and functions of the Magnolia Angular Editor — a lightweight, fully-featured library connecting Angular 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/angular-editor
is the latest version of the Magnolia Angular Editor. |
Reference
<editable-component>
The wrapping component for components.
It can only be used inside the customView
of the editable-area
.
The component determines which Angular component to render based on the mgnl:template
value of the node and the componentMappings`
supplied with the editorContext.setComponentMapping
.
Component dialog properties and areas are passed to the component as input properties.
<editable-page>
The wrapping component for Magnolia-managed page content.
It determines which Angular component to render based on the mgnl:template
value of the content
and the component mappings set in the EditorContextService
.
Page dialog properties and areas are passed to the component as input properties.
In the editor view of 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. Example endpoint definition
An example response can be seen here. |
Example
import { Component, Input } from '@angular/core';
import { EditorContextService } from '@magnolia/angular-editor';
import { HomeComponent } from './pages/home.component';
const config = {
componentMapping: {
'spa:pages/Home': HomeComponent,
},
};
@Component({
selector: 'app-root',
template: `<editable-page [content]="content"></editable-page>`,
styles: [],
})
export class AppComponent {
@Input() content: any;
constructor(private editorContext: EditorContextService) {
this.editorContext.setComponentMapping(config.componentMapping);
this.getContent();
}
async getContent() {
const contentRes = await fetch('http://localhost:8080/magnoliaAuthor/.rest/pages/spa-home');
const content = await contentRes.json();
if (this.editorContext.inIframe()) {
const templateAnnotationsRes = await fetch(
'http://localhost:8080/magnoliaAuthor/.rest/template-annotations/v1/spa-home'
);
const templateAnnotations = await templateAnnotationsRes.json();
this.editorContext.setTemplateAnnotations(templateAnnotations);
}
this.content = content;
}
}
editable-area
attribute directive
The wrapping component for areas.
The component can only be used inside the Angular components that are instantiated by the editorContext
. That is, the Angular component must be in the componentMappings
object set with the editorContext.setComponentMapping
.
By default, the area directive loops over all of its child components.
editable-area
renders Angular 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 with editorContext.setComponentMapping
. The properties of each component and areas (if any) are passed as properties to the child components.
The default behavior can be changed with customView
.
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 |
---|---|
|
Area content that is passed as prop to the parent component where the
|
|
Required only when using
|
|
Function to overwrite the default behavior of the
|
EditorContextService
A set of helper functions.
- Example
import { EditorContextService } from '@magnolia/angular-editor';
export class AppComponent {
constructor(private editorContext: EditorContextService) {
// ...
}
}
EditorContextService.inIframe
Using EditorContextHelper.getMagnoliaContext is the recommended approach.
global.mgnlInPageEditor is deprecated and not necessary.
|
EditorContextService.setComponentMapping
A function to set a configuration object containing a component mappings object with mappings between the mgnl:template
values and Angular components.
- Example
import { EditorContextService } from '@magnolia/angular-editor';
import { HomeComponent } from './pages/home.component';
const config = {
componentMapping: {
'spa:pages/Home': HomeComponent,
},
};
export class AppComponent {
constructor(private editorContext: EditorContextService) {
this.editorContext.setComponentMapping(config.componentMapping);
}
}
EditorContextService.setUseInputs
Available since version 1.5
of the @magnolia/angular-editor, a function to set properties annotated with Input
.
Usage notes
The distinction between properties and inputs is bypassed if all properties of a Magnolia node are set directly as properties on the corresponding Angular component.
Version 1.5
introduces a check to determine whether a property is an input. If yes, the setInput
method is used to properly set the property up as an input.
The feature is disabled by default. You need to call the method to activate it. Use the Input()
annotation in your components.
import { Component, Input } from "@angular/core";
@Component({
template: `
<div>
<h2>{{ title }}</h2>
</div>
`,
standalone: true,
})
export class TitleComponent {
@Input() title: string;
}
EditorContextService.setTemplateAnnotations
or EditorContextService.setTemplateDefinitions
A function to set template information required for the Page Editor to create the authoring UI (the green bars).
The Please update your project to use the See it, for example, in our minimal headless SPA demos. The
|
-
templateAnnotations
are fetched from<MAGNOLIA_INSTANCE>/.rest/template-annotations/v1/<PAGE_PATH>
- Example
-
https://demo.magnolia-cms.com/.rest/template-annotations/v1/travel
-
templateDefinitions
are fetched from<MAGNOLIA_INSTANCE>/.rest/template-definitions/v1/<PAGE_TEMPLATE>
- Example
-
https://demo.magnolia-cms.com/.rest/template-definitions/v1/travel-demo:pages/home
- Example
import { EditorContextService } from '@magnolia/angular-editor'; import { HomeComponent } from './pages/home.component'; const config = { componentMapping: { 'spa:pages/Home': HomeComponent, }, }; export class AppComponent { constructor(private editorContext: EditorContextService) { // ... } async getTemplateAnnotations() { if (this.editorContext.inIframe()) { const templateAnnotationsRes = await fetch( 'http://localhost:8080/.rest/template-annotations/v1/spa-home' ); const templateAnnotations = await templateAnnotationsRes.json(); this.editorContext.setTemplateAnnotations(templateAnnotations); } } }
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 { EditorContextService } from '@magnolia/angular-editor';
export class AppComponent {
constructor(private editorContext: EditorContextService) {
// ...
}
async getPage() {
const requestUrl = 'https://foo.bar/travel/?mgnlPreview=false&mgnlChannel=desktop';
const spaRootNodePath = '/home';
const languages = ['en', 'de'];
const magnoliaContext = this.editorContext.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 Angular Editor, see minimal-headless-spa-demos
.
Changelog
A list of notable changes for any given version is available on the changelog page.
Known issues
Lazy component loading not working with Angular v17+ SSG
The prerendering (SSG) using the application builder (introduced in Angular v17) breaks the component lazy-loading feature of the Magnolia front-end library.
Workaround
Use the legacy @angular-devkit/build-angular:prerender
instead.