JavaScript Models module
Edition | CE |
---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
1.1.1 |
- Related topics
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.1</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:
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 |
---|---|
|
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 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 |
---|---|
|
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 |
–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 |
---|---|
|
Required The value must be
When omitting Please also read Template definition to learn more information about the other properties. |
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
-
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)