Magnolia Vue Editor

This page describes the installation, components and functions of the Magnolia Vue Editor — a lightweight, fully-featured library connecting Vue projects with the WYSIWYG authoring experience of the Magnolia Pages app.

Magnolia Vue Editor only supports Vue 3.
For Vue 2, see the @magnolia-services/vue2-editor site.

Installation

To install the editor, open the command prompt and enter the following command.

npm install @magnolia/vue-editor
vue editor is the latest version of the Magnolia Vue Editor.

Reference

<EditableArea>

The wrapping component for areas.

The component can be used only inside the Vue components that are instantiated by EditablePage. That is, the Vue 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 Vue 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

areaConfig

An object with default values for boolean attributes fallthrough: true, passAttrsToChildComponents: false and unwrapAttrsToChildComponents: false, used if the property is missing in an EditableArea.

Configurable attributes

  • fallthrough: Controls attribute fallthrough behavior as described in the Vue.js documentation.

  • passAttrsToChildComponents: Passes unconsumed attributes from EditableArea to its child components (EditableXXX for content-only cases, slots, or custom views).

    Attributes are wrapped in an attrs property to ensure compatibility with the class attribute.

  • unwrapAttrsToChildComponents: Bypasses wrapping unconsumed attributes in EditableArea within an attrs property.

    As a workaround, className can be used instead of class, for example:

    ...
<EditableArea className="classValue" custom="customValue" :content="content"
area-config="{fallthrough: true, passAttrsToChildComponents: true, unwrapAttrsToChildComponents: true}"
v-slot="{custom, className, content}"> (1)
  <div :class="className" :custom="custom"> (1)
    {{ content.title }}
  </div>
</EditableArea>
...
    1 With className, you don’t need to wrap the attributes with attrs (attrs.custom and so on).
    className isn’t officially documented on the Vue.js website.
Example configuration for a slot element
...
<EditableArea class="classValue" custom="customValue" :content="content"
area-config="{fallthrough: true, passAttrsToChildComponents: true, unwrapAttrsToChildComponents: false}"
v-slot="{attrs, content}">
  <div :class="attrs.class" :custom="attrs.custom">
    {{ content.title }}
  </div>
</EditbleArea>
...
...
<div class="classValue" custom="customValue">
  <div content="[object Object]" class="classValue" custom="customValue">
    My title
  </div>
</div>
...

content

Area content that is passed as a property to the parent component where the EditableArea is used.

Example
<template>
  <div>
    <EditableArea v-if="main" v-bind:content="main" />
  </div>
</template>

<script>
import { EditableArea } from '@magnolia/vue-editor';

export default {
  name: "Home",
  components: {
    EditableArea
  },
  props: ["main"]
};
</script>

elementType

EditableArea wraps its children components in a single div element. The wrapping element can be changed by passing a new element type with elementType, which must be a valid DOM element passed as string.

Example
<EditableArea v-bind:content="main" />
/*
<div>
  ...children
</div>
*/

<EditableArea v-bind:content="main" v-bind:elementType='ul' />
/*
<ul>
  ...children
</ul>
*/

customView

Function to overwrite the default behavior of EditableArea.

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

Examples
<template>
  <div>
    <EditableArea v-if="main" v-bind:content="main" v-bind:customView="customView" />
  </div>
</template>

<script>
import { EditableArea } from '@magnolia/vue-editor';
import CustomView from './CustomView.vue';

export default {
  name: "Home",
  components: {
    EditableArea
  },
  props: ["main"],
  data() {
    return {
      customView: CustomView
    }
  }
};
</script>
<template>
  <div>
    <EditableComponent v-for="childContent in components" v-bind:key="childContent['@id']" v-bind:content="childContent" />
  </div>
</template>

<script>
import { EditableComponent } from '@magnolia/vue-editor';

export default {
  name: 'customView',
  props: ['content'],
  components: { EditableComponent },
  computed: {
    components() {
      return this.content ? this.content['@nodes'].map(nodeName => this.content[nodeName]) : [];
    }
  }
}
</script>

<EditableComponent>

The wrapping component for components.

EditableComponent component can only be used inside the customView of the EditableArea.

The component determines which Vue 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.

Properties

Property Description

content

Component content that is passed as part of area content.

<EditablePage>

The wrapping component for Magnolia-managed page content.

It determines which Vue 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

content

required

Page content response coming from Magnolia Delivery API.

Example endpoint definition
$type: jcrDeliveryEndpoint_v2
workspace: website
limit: 100
systemProperties:
  - mgnl:template
depth: 10
nodeTypes:
  - mgnl:page
childNodeTypes:
  - mgnl:area
  - mgnl:component

An example response can be seen here.

config

required

Configuration object containing the componentMappings object with mappings between the mgnl:template values and Vue components.

Example
import Home from './pages/Home.vue'

const config = {
  componentMappings: {
    'spa:pages/Home': Home,
  },
};

templateAnnotations

Template information required for the Page Editor to create the authoring UI (the green bars). templateAnnotations are fetched from

<MAGNOLIA_INSTANCE>/.rest/template-annotations/v1/<PAGE_PATH>
Example
https://demo.magnolia-cms.com/.rest/template-annotations/v1/travel

magnoliaContext

required

Introduced with front-end SDK v2, the property is used to determine the page mode (edit/preview).

It holds properties that support page rendering, such nodePath, searchParams, and others. For more details, see the current list of these properties and the description below.

It replaces the previous iframe-based detection (inEditor, inEditorAsync).

Example

<script setup lang="js">
import {
  fetchPageContent,
  fetchTemplateAnnotations,
} from '@/app/services/magnolia-service';
import { environment } from '@/environments/environment';
import config from '@/magnolia.config';
import { EditorContextService } from '@magnolia/frontend-helpers-base';
import { EditablePage } from '@magnolia/vue-editor';
import { onMounted, ref, watch } from 'vue';
import { useRoute } from 'vue-router';

defineOptions({
  name: 'MagnoliaPageResolver',
});

const content = ref(null);
const templateAnnotations = ref(null);
const configRef = ref(config);
const magnoliaContextRef = ref(null);
const route = useRoute();

const loadPageContent = async () => {
  const languages = environment.languages;
  const nodeName = environment.appBase;

  const magnoliaContext = EditorContextService.getMagnoliaContext(
    window.location.href,
    nodeName,
    languages
  );
  magnoliaContextRef.value = magnoliaContext;
  const [contentState, templateAnnotationsState] = await Promise.allSettled([
    fetchPageContent(magnoliaContext, environment.pageBase),
    fetchTemplateAnnotations(
      magnoliaContext,
      environment.templateAnnotationsBase
    ),
  ]);
  const content = contentState.value;

  const templateId = content['mgnl:template'];
  if (!templateId) {
    return;
  }
  const templateAnnotations = templateAnnotationsState.value;

  return {
    content,
    templateAnnotations,
  };
};

watch(
  () => route.path,
  async () => {
    const data = await loadPageContent();
    content.value = data.content;
    templateAnnotations.value = data.templateAnnotations;
  }
);

onMounted(async () => {
  const data = await loadPageContent();
  content.value = data.content;
  templateAnnotations.value = data.templateAnnotations;
});
</script>

<template>
  <EditablePage
    v-if="content"
    :content="content"
    :templateAnnotations="templateAnnotations"
    :magnoliaContext="magnoliaContextRef"
    :config="configRef"
  />
</template>

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

requestUrl

string

A full request/site URL (e.g., https://foo.bar or https://foo.bar?mgnlPreview=false&mgnlChannel=desktop).

For example, in a browser, it can be read with window.location.href. For other frameworks use the framework’s specific way of getting full URL.

spaRootNodePath

string

Magnolia’s root node path of the SPA website e.g. /foo or /foo/bar.

languages

array of strings

Website language(s) passed as an array of strings (e.g., ['en', 'de']).

The first language in the array is the default locale.

magnoliaContext object

Property Type Description

isMagnolia

boolean

Specifies whether the request comes from Magnolia app e.g. Pages app.

isMagnoliaEdit

boolean

Specifies whether the request comes from Magnolia app in edit mode.

isMagnoliaPreview

boolean

Specifies whether the request comes from Magnolia app in preview mode.

version

string

The version number.

This is only present if the request comes from the Magnolia app for a specific version.

nodePath

string

Magnolia’s node path for requested content.

currentLanguage

string

The language for requested content.

searchParams

object

Object with search parameters of the requestUrl enriched with Magnolia’s specific parameters.

search

string

String with search parameters of the requestUrl enriched with Magnolia’s specific parameters.

Example

import { EditorContextHelper } from '@magnolia/vue-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 Vue Editor, see minimal-headless-spa-demos.

Issues

Content mismatches on NuxtJS

To prevent content mismatches that trigger the Hydration completed but contains mismatches. error in the console of your production environment, add the following configuration to nuxt.config.ts:

...
build: {
    transpile: ["@magnolia/vue-editor", "@magnolia/template-annotations"],
  },

  alias: {
    "@magnolia/vue-editor": "@magnolia/vue-editor/src/main.js",
    "@magnolia/template-annotations":
      "@magnolia/template-annotations/src/index.js",
  },
...

Changelog

A list of notable changes for any given version is available on the changelog page.

Feedback

Headless

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules