Javascript Models

Developer productivity Bundled: Community Edition Version 2.0.0 Magnolia 6.2.17+ compatible

License

MLA, GPL

Issues

Git

Git

Maven site

The minimum baseline required for Javascript Models module version series 2.x is:

  • GraalVM 22.0.0

  • Magnolia 6.2.17

  • JDK 11

The Magnolia Javascript Models module enables developers to build JavaScript functionality that executes on the server. This module means you can avoid using Java code and complex deployment configurations.

With this module, you can:

  • Develop and use models written in JavaScript.

  • Write your business logic, save it, and see it in action immediately.

  • Eliminate downtime for your authors, and more importantly, for your customers.

You are no longer limited to using Java 14 and below. You can use the latest JDK.

Installing with Maven

Add the following to your bundle:

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

Your Maven build may include the original Javascript Models 1.2 module. To prevent this from happening, exclude the old version from the webapp POM file under <dependencies> like this:

your-webapp-maven-project/pom.xml
<project>
  ...
  <dependencies>
    <dependency>
      <groupId>info.magnolia.bundle</groupId>
      <artifactId>magnolia-community-webapp</artifactId>
      <type>war</type>
      <exclusions>
        <exclusion>
          <groupId>info.magnolia.javascript-models</groupId>
          <artifactId>magnolia-module-javascript-models</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

Installing in a bundle

If you have an existing bundle, perhaps obtained by using the Magnolia CLI, you must add the Javascript Models module and its dependencies to each /WEB-INF/lib directory.

  • magnolia-module-javascript-models-2.0.0.jar

  • truffle-api-22.0.0.jar

  • graal-sdk-22.0.0.jar

  • js-22.0.0.jar

  • regex-22.0.0.jar

  • js-scriptengine-22.0.0.jar

  • profiler-22.0.0.jar

  • chromeinspector-22.0.0.jar

Using a standard Magnolia bundle, these directories would be:

  • apache-tomcat/webapps/magnoliaAuthor/WEB-INF/lib/

  • apache-tomcat/webapps/magnoliaPublic/WEB-INF/lib/

Configuration

You configure the Javascript Models module in Configuration > /modules/javascript-models. You can:

However, there’s 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

  • parent

  • root

  • def

  • ctx

  • state

  • i18n

  • log

For more information, see 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:

image

Property Description

exposedComponents

optional

The exposed components' configuration node is optional.

     <object-name>

required

An arbitrary name of an exposed object

         name

required

The name of the object.

         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.

image

Within the /modules/javascript-models/config/engineConfiguration, create the classFilter content node, adding a separate node with a property type and a fully qualified class path for each class.

GraalVM engine options

Use the engineConfiguration to configure the options passed to GraalVM when it’s initialized.

For a full list of Engine Options that you can configure, see the Context Builder API.

image

Usage

Below you can find a simple example with a template definition, a JavaScript Model class, and a FreeMarker template script. For more information, see How to work with JavaScript models or study the sample code provided on Bitbucket.

Template definition

/js-test/templates/pages/rhino.yaml
title: Rhino
class: info.magnolia.module.jsmodels.rendering.ConfiguredJavascriptTemplateDefinition (1)
templateScript: /js-test/templates/pages/rhino.ftl
renderType: freemarker
modelClass: info.magnolia.module.jsmodels.rendering.JavascriptRenderingModel (2)
modelPath: /js-test/templates/another-location/rhino.js (3)
parameters: (4)
  myBoolParam: true
  myIntParam: 10
Property Description

class

Required

The class must be info.magnolia.module.jsmodels.rendering.ConfiguredJavascriptTemplateDefinition or a class that extends it.

modelClass

Required

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

When omitting 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.

See also Template definition to learn more information about the other properties.

modelPath

If the path does not match the name of the template, as specified above, you need to declare the path to the JavaScript class here. This is the resources path reference.

parameters

This is a free-form set of parameters that you can use within your JavaScript class that would look like this:

var Dumbo = function () {
    this.getMyInt = function () {
        return this.parameters.myIntParam;
    }
};
new Dumbo();

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(); (1)
1 At the end of the file, you must create an instance!

You should understand the difference of when to use this, and when not to. If you are accessing something within the context of your Javascript class, you use this. If you are accessing and exposedComponent, you do not.

In Default available objects, those variables are within the context of your Javascript code. Things defined in config under exposedComponents are global. Here is an example:

var Dumbo = function () {
    this.getRandomNumber = function () {
        this.log.info('Getting a Random Number'); (1)
        cmsfn.getContentById(id); (2)
        return Math.random();
    }
};
new Dumbo();
1 log is within the context of the JavaScript object.
2 cmsfn is exposed as a global object.

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

To interpret JavaScript, GraalVM creates a compiled version of a JS model. For performance reasons, Magnolia caches 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 you can disable it by setting the Magnolia property magnolia.develop to true (for more details, see Configuration management).

Samples

A few samples are in the javascript-model-samples repository.

Currently, you need to check out the JSMODELS-24 branch with Javascript Models 2.0.

cd javascript-model-samples
git checkout JSMODELS-24

If you are using a Magnolia bundle provided by Magnolia CLI’s jumpstart command, you must download and add the MTK 2.0.2 JAR to your /WEB-INF/lib webapp directories.

Changelog

The Changelog covers all updates related to this module.

Version Notes

2.0.0

2.0-beta1

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Javascript Models docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules