Backend Live Demo

If you do not currently have the Magnolia CLI package installed, in the terminal, run:

In a terminal, navigate to the backend-live-demo/magnolia directory (in the git repository) and run:

Choose magnolia-community-demo-webapp or magnolia-dx-core-demo-webapp as the version to download.

Now we are ready for Step 1. If you need some help, you can use Git to compare the start branch to the step1 branch.

For your convenience, we have provided an import file to create the page structure that we’ll be working from. The first thing we need to do is import that file.

If you expand the page tree, you should see that you have a locked column populated by true and false. What we want is to see a 🔒 icon when this value is true and nothing when it is false.

Let’s make sure we use Magnolia’s Best Practices and do proper Dependency Management. The module that we will be depending on in order to add a custom Column Definition is backend-live-ui Version 1.0 and higher. Open magnolia/light-modules/backend-live-demo-lm/module.yaml and add this dependency to the dependencies property like this:

By using the backend-live-ui, all we need to do is create a new Column Definition is to add our Javascript file, define the function apply within our new object that will be returning some HTML, then wire it up in the YAML definition. So let’s do that now.

We will create our Javascript resources within the backendScripts folder. It isn’t required that you place your Backend Javascript files here, but it is highly suggested that we all follow some standard best-practices. The file will be called: backend-live-demo-lm/backendScripts/valueProviders/booleanIcon.js and override the apply method. Here’s how your skeleton-code should look:

Now we can use this custom Column in our pages-app.yaml decorator. Of course, this will just print TODO, as you can see in the return statement, but at least we can wire this thing up. To do this, open the decorator magnolia/light-modules/backend-live-demo-lm/decorations/pages-app/apps/pages-app.yaml and modify the locked column property like this:

Before we move on, let’s talk about what we just did. Fortunately, the structure of this definition will be the same for all other types of custom code we’ll be using today. We’ve added three new properties: $type, modelPath, and parameters. Here’s what each indicates:

At this point, we have provided the parameters, but if you recall our Javascript code, the only thing that will be accomplished at this point is a log message printed to the running Magnolia log, and the locked column will display "TODO". You can verify that this works by simply reloading the Pages app, and you should see many entries in the log file with our message. In our next step, we’ll add some business logic to make this Column Definition behave the way we really want.

We will not fulfill part 2 of the use case: "A custom Action Definition to toggle the boolean locked property when clicked. This results in two actions, both using the same Action Definition."

We will now introduce another Backend Live module, backend-live-actions. Just like before, we should exercise best practices by adding it to our magnolia/light-modules/backend-live-demo-lm/module.yaml with the following:

Using backend-live-actions, all you need to do now is to create a Javascript object, write the execute business logic, wire-up the app’s YAML definition, and enjoy the fruits of your labor.

We will start by creating our Javascript resources within the backendScripts folder. The file will be called: backend-live-demo-lm/backendScripts/actions/changeValue.js and define the abstract execute method. Here’s how your skeleton-code should look:

We will start by wiring it up so that we can see if the log message appears when we click the button. We already have our backend-live-demo-lm/decorations/pages-app/apps/pages-app.yaml decorator, so let’s modify it to use this action. Here’s the YAML definition:

Open the Pages App and click on any page. You should see that there are two buttons, "Turn on Lock" and "Turn off Lock". If you click on either, you should see in the log file something similar to this:

It’s time to make this thing do something useful. What we would like to do is to change the property locked to true when "Turn on Lock" is clicked, and false when "Turn on Lock" is clicked. You could toggle the value, but that could make labeling this Action quite challenging, and would ruin an upcoming use case.

To accomplish this, we will be using the item.setProperty function for setting an Item’s property, and using YAML parameters to select the property name as well as the property value to change it to when clicked.

Now we can add the business logic to our ChangeValue object’s execute function with our Utility function:

Last thing before we can test this is to modify our YAML definition by adding the parameters propertyName and propertyValue. Open the pages-app.yaml decorator once again, and modify the actions like this:

Make sure to reload the Pages App for the changes to take effect. You should now be able to set the locked property to any page, and see the icon appear and disappear.

One issue, we don’t want to be able to just do that to any old page, so that’s the next step to resolve for our use case.

If you need some help in the next step, you can simply do a comparison between step2 and step3.

As we will be introducing another module, the backend-live-availability extension, let’s modify our Module descriptor, backend-live-demo-lm/module.yaml dependency with the following:

Now, using backend-live-availability, all you need to do is to create a Javascript object, write the isAvailableFor business logic, wire-up the app’s YAML definition, and that’s it.

We will create our Javascript resources within the backendScripts folder. The file will be called: backend-live-demo-lm/backendScripts/rules/IsTemplate.js and define the abstract isAvailableFor method. Here’s how your skeleton-code should look:

We can test to see if this works by wiring up the YAML definition. As usual, we’re going to update the pages-app.yaml decorator by modifying the two previously configured actions. Here’s how we do that:

You can verify this works by reloading the Pages app. You should see in your log two messages similar to:

Let’s now modify the business logic for the isAvailableFor to do what we need it to do. We’ll use cmsfn.asContentMap once again, and simply check if a parameter contains the value of the template ID we wish this function to be available for. The parameter that we will create will be called templates and will simply be a Map of templates, which is why we use the containsValue method of Java’s List object. Here’s our modified class with the necessary logic:

Last thing before testing is to add our parameter to the availability rule. That will simply look like this:

If you refersh the Pages App once again, and click on the travel page, you should see that our two new actions are not available to that page, but if you click on "Backend-Live-Demo-Parent" or any of its child pages, those actions are available.

Now, it’s time for our "One more thing" moment. We’re going to complete this use case by adding another availability rule.

If you need some help in the next step, you can simply do a comparison between step3 and step4.

Since we’ve already got everything working for backend-live-availability, we can get straight to work by creating our Javascript Object and add just a couple lines to the YAML definition.

We will first add a new Javascript class in our rules directory backend-live-demo-lm/backendScripts/rules/PropertyValueIsRule.js with this skeleton code:

Then we wire it up by adding the rule to our YAML definition in the pages-app.yaml decorator:

You can test by reloading the Pages App, and clicking on a page in the browser. You should see two lines in the log file similar to:

Now we add the business logic to simply compare what we expect the value to be, reusing our Utility getItemProperty function like this:

As you see, we need to set to parameters in the YAML definition for propertyName and propertyValue. Let’s modify the availability definitions like this: