JavaScript UI module

Edition

DX Core + Incubator (services)

Issues

JSFIELD

Git

Git

Latest

2.0.4

Compatible with Magnolia 6.2.

The JavaScript UI module allows you to create custom apps and custom form fields with JavaScript. The module requires that you have a DX Core Enterprise license.

This module is at the INCUBATOR level.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.ui</groupId>
  <artifactId>magnolia-ui-framework-javascript</artifactId>
  <version>2.0.4</version>
</dependency>

Custom form fields

Configuration

Add a JavaScript field in your dialog definition as follows:

label: Home page
form:
  implementationClass: info.magnolia.ui.javascript.form.FormViewWithChangeListener (1)
  properties:
    colorField:
      label: Background color
      $type: javascriptField (2)
      fieldScript: /my-light-module/webresources/colorField/index.html (3)
      height: 70 (4)
      defaultValue: "#00ff00" (5)
      parameters: (6)
        foo: bar
1 Must be info.magnolia.ui.javascript.form.FormViewWithChangeListener.
2 Must be javascriptField.
3 Points to a valid HTML file located in
4 The height of the field in the dialog.
5 The field default value.
6 Pass custom parameters to the Javascript field.

Message format

Communication between Magnolia and your iframe is done with message event.
An iframe can listen for dispatched messages by executing the following JavaScript:

window.addEventListener(
  'message',
  function (event) {
    if (event.data.action === 'init') {
      console.log(event.data.correlationId);
      console.log(event.data.state);
    }
  },
  false
);

Magnolia will send the following message to the field iframe:

Property Description

action

  • init: to initialize the field properties and values.

  • error: to notify the field failed the validation (either via the required flag or a validator).

  • change: to notify the field about any changes in dialog

correlationId

The id used by Magnolia to establish communication between the backend and the frontend.

It must be passed in all messages sent to the backend.

state

The component state

See the Vaadin section.

Magnolia can receive following messages from the iframe:

Property Description

action

  • changeValue: sent when the value of the form field gets updated.

  • changeFormFieldValue sent when any other value of the form should be updated.

  • changeHeight: sent when the height of the field gets updated by the user in the form.

  • callRestClient: sent when there is a call to a Magnolia rest client.

All iframe styles can be also changed directly on the DOM element e.g.:
window.frameElement.style.position = 'fixed';
window.frameElement.style.top = '0';

correlationId

The id used by Magnolia to establish communication between the backend and the frontend.

value

For changeValue, the type of the value is always a String. If you need to store complex objects, stringify it before returning it to Magnolia.

For changeFormFieldValue, fieldName indicates the form field that will be changed. The type of the value is always a String (see changeValue)

For changeHeight, send the height in pixels that the new <iframe> will be.

For callRestClient, restClientName indicates the name of the Magnolia rest client to call, restClientMethodName indicates the name of the Magnolia rest client method to call, and body opetional json body for the rest client to call.

Example:

parent.window.postMessage({
    action: 'changeValue',
    correlationId,
    value: input.value
}, '*');

parent.window.postMessage({
    action: 'changeHeight',
    correlationId,
    value: 50
}, '*');

parent.window.postMessage({
    action: 'changeFormFieldValue',
    correlationId,
    value: 50,
    fieldName: 'other-field-name'
}, '*');

parent.window.postMessage({
  action: "callRestClient",
  correlationId: correlationId,
  restClientName: "ShopProducts",
  restClientMethodName: "list",
  body: ""
}, '*');

Custom app

Configuration

Add a JavaScript app in your app definition as follows:

icon: icon-categories
class: info.magnolia.ui.contentapp.configuration.ContentAppDescriptor
appClass: info.magnolia.ui.framework.app.BaseApp
label: Custom app
subApps:
  firstApp: (1)
    class: info.magnolia.ui.javascript.app.JavascriptSubAppDescriptor (2)
    label: 1st tab
    fieldScript: /ui-framework-javascript-dev-samples/webresources/debugApp.html (3)
    parameters: (4)
      welcomeMessage: Browser
  secondApp: (5)
    class: info.magnolia.ui.javascript.app.JavascriptSubAppDescriptor
    label: 2nd tab
    fieldScript: /ui-framework-javascript-dev-samples/webresources/debugEditApp.html
    closable: false (6)
    parameters:
      welcomeMessage: Editor
1 First listed subApp:
will be shown when opening the app (e.g. via Admincentral tile),
will have not closable tab.
2 It must be info.magnolia.ui.javascript.app.JavascriptSubAppDescriptor.
3 Points to a valid HTML file located in
4 Pass custom parameters to the Javascript field.
5 All but the first listed subApps:
by default will not be shown when opening the app,
by default will have closable tabs.
6 Set to false to modify the default behaviour described in point 5.

Message format

Communication between Magnolia and your iframe is done with message event.
An iframe can listen for dispatched messages by executing the following JavaScript:

window.addEventListener(
  'message',
  function (event) {
    if (event.data.action === 'init') {
      console.log(event.data.correlationId);
      console.log(event.data.state);
    }
  },
  false
);

Magnolia will send the following message to the field iframe:

Property Description

action

  • init: to initialize the field properties and values.

correlationId

The id used by Magnolia to establish communication between the backend and the frontend.

It must be passed in all messages sent to the backend.

state

The component state

See the Vaadin section.

Magnolia can receive following messages from the iframe:

Property Description

action

  • changeLocation: Change the Vaadin location (used to open subapps).

correlationId

The id used by Magnolia to establish communication between the backend and the frontend.

app

The name of the app to forward to

subapp

The name of the subapp to forward to

tabTitle

The target subapp tab caption

urlParameter

The concatenated parameters to be passed to the target subapp with state object

Example:

parent.window.postMessage({
    action: 'changeLocation',
    correlationId,
    app: 'custom-app',
    subapp: 'secondApp',
    tabTitle: 'My tab title',
    urlParameter: 'my-object-id'
}, '*');

Vaadin

Vaadin shares a component state with the Javascript field, here is its format:

Property Description

contextPath

The current Magnolia instance context path.

Example: /author

fieldScriptUrl

The field script URL defined in the yaml definition.

Example:

/my-light-module/webresources/colorField/index.html

parameters

The parameters defined in the yaml definition.

currentUser

The current user.

locale

The current locale.

Only in Custom form fields

currentNode

The current node.

This is null in case of a node creation.


Example 

{
    "id":"8346c262-689b-4622-98ac-a56e15c59163",
    "name":"tests",
    "path":"/tests",
    "properties":{
        "mgnl:created":"2022-01-21T11:42:04.143+01:00",
        "mgnl:template":"my-light-module:pages/home",
        "jcr:created":"2022-01-21T11:42:04.143+01:00",
        "mgnl:lastModifiedBy":"superuser",
        "jcr:createdBy":"admin",
        "mgnl:createdBy":"superuser",
        "jcr:uuid":"8346c262-689b-4622-98ac-a56e15c59163",
        "jcr:primaryType":"mgnl:page",
        "colorField":"#ff0040",
        "mgnl:lastModified":"2022-01-21T11:42:04.143+01:00"
    },
    "type":"mgnl:page"
}

defaultValue

The default value defined in the yaml definition.

formFields

The values of the other fields of the current form.

height

The height defined in the yaml definition, or the updated value sent in case the field gets enlarged from the UI.

Example: 50

value

The current value of the form property.

readOnly

Whether the field is readOnly or not.

Only in Custom app

urlParameter

Used to communicate parameters between two javascript subapps.

Samples

Check out some samples here.

Changelog

Version Notes

2.0.4

Changelog

2.0.3

Changelog

2.0.2

Changelog

2.0.1

Changelog

2.0

Changelog

1.2.3

Changelog

1.2.2

Changelog

1.2.1

Changelog

1.2

Changelog

1.1.8

JSFIELD-14

1.1.7

JSFIELD-6

JSFIELD-5

1.1.6

JSFIELD-2

1.1.5

JSFIELD-1

1.1.4

Support for Magnolia 6.2.12

1.1.3

Add support in content apps

1.1.1

Bug fixes

1.1

Add the message action

  • Add the error notification

1.0

Initial release.
Feedback

Incubators

×

Location

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

You are currently perusing through the JavaScript UI module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules