Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
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.
At least version 5.7.16 of Magnolia is required for module version 1.2 or higher.
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.).
<version/>
in the dependency.<dependency> <groupId>info.magnolia.javascript-models</groupId> <artifactId>magnolia-module-javascript-models</artifactId> </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:
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 name | Value |
---|---|
modules | |
javascript-models | |
config | |
engineConfiguration | |
exposedComponents | |
cmsfn | |
name | cmsfn |
componentClass | info.magnolia.templating.functions.TemplatingFunctions |
Properties:
| optional The exposed components configuration node can be omitted. |
| required An arbitrary name of an exposed object |
| required The name of the object which will be used to reference it. |
| 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 name | Value |
---|---|
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 name | Value |
---|---|
config | |
engineConfiguration | |
engineOptions | |
--no-java | --no-java |
--no-syntax-extensions | --no-syntax-extensions |
Properties:
| optional The engine options configuration node can be omitted. |
| required An arbitrary name of an exposed object |
| required The name of the object which will be used to reference it. |
| required A fully qualified class name of the exposed object. |
Example engine options:
Option | Meaning |
---|---|
--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
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
modelClass | Required The value must be |
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)