JavaScript UI module

Developer productivity Unbundled: Extension Version 3.1.0 Magnolia 6.3 compatible

Issues

JSFIELD

Git

Git

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.

Installing with Maven

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

  • Version 3.0.X

  • Version 3.1 and later

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

Core dependency is required

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

To use javascript form fields include:

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

To use javascript subapps include:

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

To use javascript dialogs include:

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

Ecommerce

To activate product picker feature:

  1. Make sure E-commerce module is set up properly.

  2. Go to your /<your-maven-module>/src/main/resources/META-INF/magnolia/<your-maven-module>.xml

  3. Ensure you have the following in the file.

    <your-maven-module>/src/main/resources/META-INF/magnolia/<your-maven-module>.xml
      <components>
    <id>main</id>
    <component>
      <type>info.magnolia.ui.javascript.dialogs.impl.EcommerceDialogResultMapper</type>
      <implementation>info.magnolia.ui.javascript.dialogs.impl.EcommerceDialogResultMapper</implementation> (1)
      <scope>singleton</scope>
    </component>
  </components>
    1 Ensure you enable the EcommerceDialogResultMapper component in scope main.

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

  • restResponse: to notify the field about the response of a called rest client

  • dialogResponse: to notify the field the selection of a chooser dialig

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.

  • openDialog: sent to open a native Magnolia dialog.

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 resolving complex object such as JSON array, you need to configure the following reference resolver: info.magnolia.ui.javascript.resolver.NodeListJcrReferenceResolverDefinition

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 optional json body for the rest client to call.

For openDialog, callerId indicates a unique id of the frontend component that posted the command, dialogId indicates a registered dialog, workspace used to specify workspace for chooser dialogs. workspace property is either a JCR workspace or the value rest for REST based datasources or ecommerce for integrations using Commerce integration framework. Note: Commerce integration framework has to be installed separately in your webapp to use ecommerce based dialogs.

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: ""
}, '*');

parent.window.postMessage( {
  action: "openDialog",
  correlationId,
  dialogId: "ui-framework-core:chooser",
  workspace: "personas",// required for chooser dialogs, optional for standard dialog
  callerId: "unique-identifier",
}, "*",);

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'
}, '*');

Custom javascript dialogs

Configuration

Dialog definition

Add a JavaScript dialog as follows:

fieldScript: /<your-lm>/webresources/js-dialog/app.html (1)
parameters:
  your-test: parameter
1 Points to a valid HTML file located in

Note: To ensure that the dialog matches Magnolia’s new UI you can use an implementation that uses Magnolias new Design System. See the documentation for more details.

Open dialog action

Add an open dialog action as follows:

openJSDialog:
  label: Open JS Dialog
  icon: icon-file-image
  $type: openJavascriptDialogAction (1)
  javascriptDialogId: <your-lm>:<your-dialog> (2)
1 $type has to be set to openJavascriptDialogAction.
2 Points to the id of the defined dialog.

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

  • restResponse: to notify the field about the response of a called rest client

  • dialogResponse: to notify the field the selection of a chooser dialig

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

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

  • openDialog: sent to open a native Magnolia dialog.

  • closeDialog: sent to close the js dialog.

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.

For openDialog, callerId indicates a unique id of the frontend component that posted the command, dialogId indicates a registered dialog, workspace used to specify workspace for chooser dialogs. workspace property is either a JCR workspace or the value rest for REST based datasources or ecommerce for integrations using Commerce integration framework. Note: Commerce integration framework has to be installed separately in your webapp to use ecommerce based dialogs.

Example:

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

parent.window.postMessage( {
  action: "openDialog",
  correlationId,
  dialogId: "ui-framework-core:chooser",
  workspace: "personas",// required for chooser dialogs, optional for standard dialog
  callerId: "unique-identifier",
}, "*",);

parent.window.postMessage( {
  action: "closeDialog",
  correlationId,
}, "*",);

Developer sample

A developer sample can be found here.

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

3.1.0

Changelog

3.0.1

Changelog

3.0.0

Initial release (Magnolia 6.3 support)
Feedback

DX Core

×

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