Javascript Models

Edition

License

MLA, GPL

Issues

JSMODELS

Git

Git

Maven site

JSMODELS

Latest

1.2.0

Compatible with Magnolia 6.2 latest.

Available on SPA/Headless

This module requires Java 8-14, which still includes support for Nashorn. See the Certified stack page for the supported Java versions.

The Nashorn JavaScript engine, used by Javascript Models 1.2, was deprecated in JDK 11 and removed in JDK 15. For usage with JDK 11 and higher, please use Javascript Models 2.x, which uses GraalVM.

Javascript Models 1.2 is still included in the 6.2.x Magnolia bundles for backwards compatibility.

Overview

The JavaScript Models module adds the ability to develop and use models written in JavaScript. You can implement a JavaScript model with light development, enabling fast development and deployment without the need for Java, Maven or WAR deployment. Include your JavaScript model as a Magnolia resource in your project.

Due to performance issues, we do not recommend using this module as part of your Magnolia Cloud deployment.

Java, JavaScript and Nashorn

Java 8 introduced support for a JavaScript engine called Nashorn, which can interpret JavaScript code in a Java application. For more information, see Further reading.

Installing with Maven

Since the release of Magnolia 5.5.6, the JavaScript Models module is bundled with the magnolia-community-webapp. All the other webapps and bundles inherit the module from this webapp (see also preconfigured Magnolia bundles and webapps.).

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

javascript-models

<dependency>
  <groupId>info.magnolia.javascript-models</groupId>
  <artifactId>magnolia-module-javascript-models</artifactId>
  <version>1.2.0</version>
</dependency>

Configuration

The JavaScript Models module can be configured in Configuration > /modules/javascript-models in order to:

Expose components such as templating functions.
Limit access to Java API with:
- Class filter
- Nashorn engine options

However, there is little need for any configuration since the module provides helpful rendering context objects out of the box.

Default available objects

Without any configuration, the following objects are available in all models:

content
def
ctx
state
i18n

For more information, see Rendering context objects.

Exposing components

You can expose (custom) components to the models in the module’s configuration. A typical use case is adding Templating functions.

If you want to use cmsfn, you have to configure it under exposedComponents:

Property Description

Property	Description
`exposedComponents`	optional The exposed components' configuration node can be omitted.
`<object-name>`	required An arbitrary name of an exposed object
`name`	required The name of the object which will be used to reference it.
`componentClass`	required A fully qualified class name of the exposed object.

exposedComponents

optional

The exposed components' configuration node can be omitted.

<object-name>

required

An arbitrary name of an exposed object

name

required

The name of the object which will be used to reference it.

componentClass

required

A fully qualified class name of the exposed object.

Class filter

The class filter is one of the options with which you can limit access to the Java API.

The value of the class property has to be a fully qualified class name of the class implementing jdk.nashorn.api.scripting.ClassFilter.

Nashorn engine options

Use the engineOptions to configure the options passed to Nashorn when it is initialized.

For instance, you can limit the access to Java API by disabling Nashorn extensions or by implementing a ClassFilter.

Property Description

Property	Description
`engineOptions`	optional The engine options configuration node can be omitted.
`<object-name>`	required An arbitrary name of an exposed object
`name`	required The name of the object which will be used to reference it.
`componentClass`	required A fully qualified class name of the exposed object.

engineOptions

optional

The engine options configuration node can be omitted.

<object-name>

required

An arbitrary name of an exposed object

name

required

The name of the object which will be used to reference it.

componentClass

required

A fully qualified class name of the exposed object.

Example engine options:

Option Meaning

Option	Meaning
`-no-java`	Turns off Java specific syntax extensions like `Java`, `Packages`, etc.
-no-syntax-extensions`	Only standard ECMAScript syntax is supported.

-no-java

Turns off Java specific syntax extensions like Java, Packages, etc.

-no-syntax-extensions`

Only standard ECMAScript syntax is supported.

Usage

Below you can find a simple example with a template definition, a JavaScript Model class and a FreeMarker template script. For further explanations, please read also How to work with JavaScript models or study the sample code provided on Bitbucket.

Template definition

/js-test/templates/pages/rhino.yaml

title: Rhino
templateScript: /js-test/templates/pages/rhino.ftl
renderType: freemarker
modelClass: info.magnolia.module.jsmodels.rendering.JavascriptRenderingModel
#class: info.magnolia.module.jsmodels.rendering.JavascriptTemplateDefinition
#modelPath: /js-test/templates/another-location/rhino.js

Property Description

Property	Description
`modelClass`	Required The value must be `info.magnolia.module.jsmodels.rendering.JavascriptRenderingModel`. When omitting `class` and `modelPath`, the system expects the model file to be in the same location as the template definition, the expected name is `<template-name>.js`. See How to work with JavaScript models. Please also read Template definition to learn more information about the other properties.

modelClass

Required

The value must be info.magnolia.module.jsmodels.rendering.JavascriptRenderingModel.

When omitting class and modelPath, the system expects the model file to be in the same location as the template definition, the expected name is <template-name>.js. See How to work with JavaScript models.

Please also read Template definition to learn more information about the other properties.

Model class

The JavaScript model file must define a JS class which can contain properties and methods.

/js-test/templates/pages/rhino.js

var Dumbo = function () {
    this.getRandomNumber = function () {
        return Math.random();
    }
};
new Dumbo(); (1)

1	At the end of the file you must create an instance!

Template script

In the template script, reference the model object with model.

/js-test/templates/pages/rhino.ftl

<div>Here you have a random number: ${model.getRandomNumber()}</div>

Cache

In order to interpret JavaScript, GraalVM creates a compiled version of a JS model. For performance reasons, Magnolia is caching the compiled scripts. Cache entries are flushed based on the lastModified timestamp. Changes are detected by Magnolia’s Resources observation mechanism.

The JavaScript model cache is enabled by default, but it can be disabled by setting the Magnolia property magnolia.develop to true (see Configuration management).

Samples

A few samples can be found in our Bitbucket repo.

Changelog

The Changelog covers all updates related to this module.

Version Notes

Version	Notes
`1.2`	JSMODELS-26
`1.1.2`	JSMODELS-22
`1.1.1`	JSMODELS-19
`1.1`	JSMODELS-18
`1.0`	JSMODELS-17 JSMODELS-16 JSMODELS-15 JSMODELS-14 JSMODELS-13 JSMODELS-12 JSMODELS-11 JSMODELS-10 JSMODELS-9 JSMODELS-7 JSMODELS-3 JSMODELS-2 JSMODELS-1

1.2

JSMODELS-26

1.1.2

JSMODELS-22

1.1.1

JSMODELS-19

1.1

JSMODELS-18

1.0

Javascript Models

Overview

Java, JavaScript and Nashorn

Installing with Maven

Configuration

Default available objects

Exposing components

Class filter

Nashorn engine options

Usage

Template definition

Model class

Template script

Cache

Samples

Further reading

Changelog

Location

Main doc sections