JavaScript Models module

The JavaScript Models module adds the ability to develop and use models written in JavaScript. JavaScript Models can be done via Light development, enabling fast development and deployment without the need for Java, Maven or WAR deployment. JavaScript Models represent a type of Magnolia Resources.

This module requires Java 8 (support for Nashorn). 

Java, JavaScript and Nashorn

Java 8 brought in support for a JavaScript engine called Nashorn, which can interpret Javascript code in a Java application. Nashorn currently follows edition 5.1 of the ECMAScript specification, but edition 6 is planned to be supported in future releases. For more information see the Further reading section.

Installing

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

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

• magnolia-module-javascript-models.jar

Configuration

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

• Expose component 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 

Learn more about these objects on 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 :

Properties:

Class filter

The class filter is one of the options with which you can limit the 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.

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

Properties:

Example engine options:

Usage

Below you can find a simple example with a template definition, a JavaScript Model class and 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

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

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 - Defining and referencing.

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. 

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

Template script

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

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

Cache

In order to interpret JavaScript, Nashorn 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 - Properties).

Samples

A few samples can be found on our Bitbucket.

Further reading

• How to work with JavaScript models
• Oracle Nashorn: A Next-Generation JavaScript Engine for the JVM (by Julien Ponge)
• Project Nashorn (an OpenJDK project)
• JavaScript engines (Wikipedia)
• ECMAScript Language Specification (5.1 edition)