Backend Live - Javascript Availability

The Javascript Availability extension provides you with the ability to define your own Availability Rules that can be used across any definition that originally extends from info.magnolia.ui.api.availability.ConfiguredAvailabilityRuleDefinition. You just need to create a Javascript file that specifies the isAvailableFor function returning true or false.

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 Availability JAR

Using a standard Magnolia Bundle, these directories would be:

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

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

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-availability</artifactId>
  <version>1.0</version>
</dependency>

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 so that if a page has a property locked set to true the editor will not be able to open this page in the "Edit" mode.

You can simply add the backend-live-availability-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-availability-lm in your Light Modules directory.

To create your Availability 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-availability-lm/backendScripts/rules/PropertyValueIsRule.js.

The Javascript

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

backend-live-availability-lm/backendScripts/rules/PropertyValueIsRule.js
var PropertyValueIsRule = function () {
    this.isAvailableFor = function (obj) {
        return true;
    }
}
new PropertyValueIsRule();

  • Line 1: Create the Javascript Class

  • Line 2: Declare the isAvailableFor function accepting an obj parameter (this is the node we’ll be validating the availability for)

  • 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 obj node supplied to the isAvailableFor 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-availability-lm/backendScripts/rules/PropertyValueIsRule.js
loadScript("/backend-live-common-lm/backendScripts/utils.js");
var PropertyValueIsRule = function () {
    var utils = new Utils();
    this.isAvailableFor = function (obj) {
        return true;
    }
}
new PropertyValueIsRule();

  • 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 (using our this.parameters.propertyName) and compare it to this.parameters.propertyValue. If the expected values match, we will make this call "Available", otherwise not.

backend-live-availability-lm/backendScripts/rules/PropertyValueIsRule.js
loadScript("/backend-live-common-lm/backendScripts/utils.js");
var PropertyValueIsRule = function () {
    var utils = new Utils();
    this.isAvailableFor = function (obj) {
        var existingValue = utils.getItemProperty(obj, this.parameters.propertyName);
        if (existingValue === undefined || existingValue === this.parameters.propertyValue) {
            return true;
        }
        return false;
    }
}
new PropertyValueIsRule();

  • Line 5: Get the value of the property defined by the YAML in the parameters.propertyName

  • Line 6: If the value exists, then determine if the value matches the value defined by the YAML in the parameters.propertyValue, return true if so. (If the value does not exist, that means the page doesn’t define this property.)

  • Line 9: Return false by default.

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.

content

This is the item selected when clicking on the Action. If in the Pages App, it is the page node, for example.

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.

availabilityDefinition

The availability definition points specifically to the Availability definition rather than the Rule Definition itself.

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-availability-lm/decorations/pages-app/apps/pages-app.yaml
subApps:
  browser:
    actions:
      edit:
        availability:
          rules:
            isNotLockedRule:
             $type: jsAvailability
             modelPath: /backend-live-availability-lm/backendScripts/rules/PropertyValueIsRule.js
             parameters:
               propertyName: locked
               propertyValue: false

  • Line 7: Create a new rule called isNotLockedRule

  • Line 8: Use the Backend Live Availability $type: jsAvailability

  • Line 9: modelPath is now what distinguishes its actual execution of the rule

  • 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 jsAvailability.

class

Required (if not using $type)

The class must be info.magnolia.module.backendlive.availability.JavascriptAvailabilityRuleDefinition.

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-availability-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 Availability Rules 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