JavaScript Models module

Edition	CE
License	MLA, GPL
Issues	JSMODELS
Maven site	JavaScript Models
Latest	1.1.2

Edition

License

MLA, GPL

Issues

JSMODELS

Maven site

JavaScript Models

Latest

1.1.2

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.

This module requires Java 8 or higher which includes support for Nashorn. See the Certified stack page to confirm the latest supported Java version.

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

Installing with Maven

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

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

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:

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.

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

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