Page tree
Skip to end of metadata
Go to start of metadata

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

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

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

Pre-built jars are also available for download. See Installing a module for help.

Configuration

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

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 :

Node nameValue

 modules


 javascript-models


 config


 engineConfiguration


 exposedComponents


 cmsfn


 name

cmsfn

 componentClass

info.magnolia.templating.functions.TemplatingFunctions

Properties:

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 the access to the Java API.

Node nameValue

 config


 engineConfiguration


 classFilter


 class

com.example.MyCustomClassFilterImpl

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.

Node nameValue

 config


 engineConfiguration


 engineOptions


 --no-java

--no-java

 --no-syntax-extensions

--no-syntax-extensions

Properties:

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:

OptionMeaning
--no-javaTurns off Java specific syntax extensions like "Java", "Packages", etc.
--no-syntax-extensionsOnly standard ECMAScript syntax is supported.

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

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

modelClass

Required

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

modelPath

Optional

When omitted, the system expects the model file to be in the same location as the template definition, the expected name is <template-name>.js .

This property is handy if you want to use the same model in different templates.

Please 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();
Line 6: 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, 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