Backend Live - Javascript UI

The Javascript UI extension provides you with the ability to define your own UI Components. So far, the only UI Component available for customization is Column Definitions, specifically the Value Provider’s apply method that returns some HTML snippet that would be injected into the columns value.

Installing with Maven

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

your-webapp-maven-project/pom.xml
<dependency>
  <groupId>info.magnolia.backendlive</groupId>
  <artifactId>backend-live-ui</artifactId>
  <version>1.0</version>
</dependency>

Installing to a Bundle

If you have an existing bundle, perhaps obtained by using the Magnolia CLI, you will need to add the modules as defined at Javascript Models 2.0, as well as its dependencies to each webapp’s /WEB-INF/lib directories:

Backend Live UI 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

Make sure to follow the Configuration for Javascript Models 2.

You should already have exposed the cmsfn Templating function to your Javascript projects, but if not, this is how the configuration should look in the Configuration app:

image

Exposed Components can be considered "global", meaning that you do not reference them with this, rather just cmsfn. This will also apply to exposedComponents you define for each definition, which we will explain later.

If you’d like a full list of the default exposeedComponents and a description, you can click "Expand for More"

Expand for More

Component Description

cmsfn

Navigate content and create links.

damfn

Get assets and renditions and create links to assets.

sitefn

Get sites and themes.

imgfn

Get links to images from any workspace.

resfn

Create links to css and js files by given patterns.

restfn

Access REST clients.

searchfn

Search pages and content.

navfn

Create site navigation.

catfn

Get categories (tags) and access content by category.
Hooray!

You are now ready to start writing your own custom Javascript component.

Usage

This example will change the behavior the Pages App showing a new column representation of the locked property. By default, the column would show the true or false value of the page, which can be more unclear. This column will show an icon for true values and nothing at all for false values.

You can simply add the backend-live-ui-lm project from Backend-Live Samples if you want to see it in action. If you want to get a more hands-on experience, you can create a folder named backend-live-ui-lm in your Light Modules directory.

To create your Column Definition with Javascript, simply create your javascript file. The best place to maintain your Javascript files is in your Light Module’s backendScripts directory. In this sample, we are creating the file: light-modules/backend-live-ui-lm/backendScripts/valueProviders/booleanIcon.js.

The Javascript

Within this file, we need to create a class, define it’s apply function, and instantiate it. This is necessary for GraalVM to access the function. Here is the generic structure:

backend-live-ui-lm/backendScripts/valueProviders/booleanIcon.js
var BooleanIcon = function () {
    this.apply = function(item) {
        return "";
    }
}
new BooleanIcon();

  • Line 1: Create the Javascript Class

  • Line 2: Declare the apply function accepting an apply parameter (this is the node we’ll be applying the column definition to)

  • Line 6: At the end of the file you must create an instance

We are going to make use of some common functionality that will be shared across multiple Backend Live modules. The function we’ll be using is called getItemProperty and simply resolves an item property from the item node supplied to the apply function.

Include Common Light Module

Since we’re using some common functionality, we’ll need to add backend-live-common-lm to our environment. If you’ve already done so, you can skip to the next section.

First, copy the backend-live-common-lm from the Backend-Live Samples project.

Now, update your module.yaml file with a dependency to this Light Module like this:

dependencies:
  ...
  backend-live-common-lm:
    version: 1.0/*

The samples using this backend-live-common-lm will make use of a property called locked on our page template. To make your life a little easier, we’ve included an import file with a set of pages using this property. To make proper use of this property, import the page by:

  1. Open the Pages App

  2. Without any other page selected in the browser subapp, click "Import".

  3. Navigate to the Samples Page import file, light-modules/backend-live-common-lm/_dev/content-to-import/website.Backend-Live-Demo.yaml, and click the "Import" button.

The locked property has no specific logical meaning behind it, it’s simply used with multiple examples to show functionality.

Add the Business Logic

Let’s start by using the above Utility class by adding the loadScript function, and instantiate the Utility like this:

backend-live-ui-lm/backendScripts/valueProviders/booleanIcon.js
loadScript("/backend-live-common-lm/backendScripts/utils.js");
var BooleanIcon = function () {
    var utils = new Utils();
    this.apply = function(item) {
        return "";
    }
}
new BooleanIcon();

  • Line 1: Load the utils.js using the Resource File Path.

  • Line 3: Instantiate the Utils class.

  • Line 8: Create a class instance.

Next, we’ll add the logic. This is quite simple. We just use the utility to get the value of the locked property. If the value matches the expected value (in this case, it’s only checking if a value is true or false), we then will render whatever we set via the YAML parameters properties.

In this sample, we allow the setting of "something" in a property called trueImg or a property called falseImg. Obviously, when the value is true, we will render trueImg…​and the vice versa. This example is expecting a simple "Emoji", but could be even some text value. If you’d like to try some different emoji’s than the one we use in this sample code, you can check out EmojiPedia.org, and just copy another value. Here’s the logic:

backend-live-ui-lm/backendScripts/valueProviders/booleanIcon.js
loadScript("/backend-live-common-lm/backendScripts/utils.js");
var BooleanIcon = function () {
    var utils = new Utils();
    this.apply = function(item) {
        if (!item.isNode()) {
            return null;
        }
        var isLocked = utils.getItemProperty(item, 'locked');
        if (isLocked) {
            if (this.parameters.containsKey('trueImg')) {
                return this.parameters['trueImg'];
            }
        } else if (this.parameters.containsKey('falseImg')) {
            return this.parameters['falseImg'];
        }
        return "";
    }
}
new BooleanIcon();

The this.parameters is something we’ll define next in our YAML definition. First, let’s discuss the other this objects you have access to.

Component Description

parameters

Custom definition items defined in the YAML file under the parameters property.

definition

This is the YAML definition that you’ve specified when declaring the $type: jsAvailability. This is the primary definition you will need to access for this rules properties.

def

This is a shorthand representation of the definition, simply used as it is carried over from previous versions.

log

This is the Magnolia Log4j log bound to the Javascript Availability Rule class. You can log debug, info, warn and error messages using this.

The YAML

Here, we will put it all together.

We will modify the Pages App using a decorator to change the "Edit" action’s availability. Here’s the YAML definition to make this happen:

backend-live-ui-lm/decorations/pages-app/apps/pages-app.yaml
subApps:
  browser:
    workbench:
      contentViews:
        tree:
          columns:
            locked:
              $type: jsColumn
              modelPath: /backend-live-ui-lm/backendScripts/valueProviders/booleanIcon.js
              parameters:
                trueImg: 🔒

  • Line 7: Modify the locked column

  • Line 8: Use the Backend Live UI $type: jsColumn

  • Line 9: modelPath is now what distinguishes its actual business logic for the rendering of the column

  • Line 10: parameters are free-form and can be reused in the Javascript via this.parameters.<NAME>

Property Description

$type

Required (if not using class)

The value must be jsColumn.

class

Required (if not using $type)

The class must be info.magnolia.module.backendlive.ui.contentapp.column.jcr.JavascriptColumnDefinition.

modelPath

Required The path to the Javascript class. 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();

exposedComponents

You can expose Java @Inject backend objects. Referencing the above YAML definition, you could then use it like this:

var Dumbo = function () {
    this.changeLocation = function (location) {
        locationController.goTo(location);
    }
};
new Dumbo();
exposedComponents operate the same way as components defined in the javascript-models configuration app under /modules/javascript-models/config/engineConfiguration/exposedComponents

     <object-name>

The arbitrary name that will be used to access the defined class.

         componentClass

The Java class that will expose its public methods to your Javascript.

         name

The arbitrary name that will be used to access the defined class.

Samples

There are light-module samples for each of the projects found in our Backend-Live Samples repository.

Once you check out the project, you can simply copy the light-modules/backend-live-ui-lm folder into your magnolia.resources.dir location (defined in YOUR-WEB-APP/WEB-INF/config/default/magnolia.properties).

If you are interested in a more complex demonstration, and tutorial on how to use multiple extensions in conjunction with each other, you may be interested in checking out our Backend Live Demo project.

Changelog

The Changelog covers all updates related to this module.

Version Notes

1.0

  • Custom Javascript UI Components Released
Feedback

Incubators

×

Location

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

You are currently perusing through the Backend Live docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules