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
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.

Properties

Property Description

content

Component content that is passed as part of area content.

<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

content

Page content response coming from Magnolia Delivery API.

Example endpoint definition

class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
limit: 100
systemProperties:
  - mgnl:template
depth: 10
nodeTypes:
  - mgnl:page
childNodeTypes:
  - mgnl:area
  - mgnl:component

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 children 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

content

Area content that is passed as prop to the parent component where the editable-area is used.

import { Component, Input } from '@angular/core';

@Component({
  template: `<div editable-area [content]="main"></div>`,
})

export class HomeComponent {
  @Input() main: any;
}

parentTemplateId

Required only when using templateDefinitions.

import { Component, Input } from '@angular/core';

@Component({
  template: `<div editable-area [content]="main" [parentTemplateId]="metadata['mgnl:template']"></div>`,
})

export class HomeComponent {
  // main is area name as defined in page/component YAML definition
  // metadata is set of extra component information added by angular-editor
  @Input() main: any;
  @Input() metadata: any;
}

customView

Function to overwrite the default behavior of the EditableArea.

customView receives one variable with all area data passed as the content property.

import { Component, Input } from '@angular/core';

@Component({
  template: `
    <div editable-area [content]="main" [customView]="customView"></div>

    <ng-template #customView let-content let-components="components">
      <ng-container *ngFor="let childContent of components">
        <editable-component [content]="childContent"></editable-component>
      </ng-container>
    </ng-template>
  `,
})

export class HomeComponent {
  @Input() main: any;
}

EditorContextService

A set of helper functions.

Example
import { EditorContextService } from '@magnolia/angular-editor';

export class AppComponent {
  constructor(private editorContext: EditorContextService) {
    // ...
  }
}

EditorContextService.inIframe

A function that returns true when run in the IFRAME app or when global.mgnlInPageEditor is set to true.

Alternatively, you can check the URL of the requested website. In the Pages app, Magnolia adds the mgnlPreview parameter to the IFRAME preview source.

Example
import { EditorContextService } from '@magnolia/angular-editor';

export class AppComponent {
  constructor(private editorContext: EditorContextService) {
    // ...
  }

  async foobar() {
    if (this.editorContext.inIframe()) {
      // ...
    }

    // Alternative approach
    if (window.location.search.includes('mgnlPreview')) {
      // ...
    }
  }
}

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.setTemplateAnnotations or EditorContextService.setTemplateDefinitions

A function to set template information required for the Page Editor to create the authoring UI (the green bars).

Use templateAnnotations.

templateDefinitions are deprecated.

  • 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);
    }
  }
}

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.

Feedback

Headless