This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.

Page tree
Skip to end of metadata
Go to start of metadata

The tools subapp is a special type of subapp which contains a list of tools. A tool is a small functional block which is defined by a ToolDefinition and is rendered as a subtab of the subapp.

Tools provide you with UI elements, basically forms, for working with configuration and content. You can use the form fields to enter and edit values and save them or trigger other actions. It also provides the ability to validate the form input thereby helping users enter correct data and reducing errors.

You can create a tool with a few lines of YAML configuration and at least one custom Java class. This reduces effort compared to creating a completely custom app 

Tool usage examples: 

  • Modify your module's configuration such as setting SMTP settings for a Mail module.
  • Query or report the usage of content items. 
  • Configure a connector to an external system.
  • Start batch processes and execute complex commands that may require user input.

In this example, the tools subapp lets you query groups and permissions associated to a given user:

The tool definition class is i18n-ized and comes with its own key generator class ToolDefinitionKeyGenerator .

ToolsSubApp definition

subApps:
  main: 
    class: info.magnolia.ui.framework.tools.ToolsSubAppDescriptor
    subAppClass: info.magnolia.ui.framework.tools.ToolsSubApp
    tools:
Node nameValue

 subApps


  tools


 class

info.magnolia.ui.framework.tools.ToolsSubAppDescriptor

 subAppClass

info.magnolia.ui.framework.tools.ToolsSubApp

<subapp name>

required

Subapp node name. This is the internal ID of the subapp. In this example it is main.

class

required

For a tools subapp must be info.magnolia.ui.framework.tools.ToolsSubAppDescriptor or a subclass.

ToolsSubAppDescriptor defines a subapp with several tools.

subAppClass

required

For a tools subapp must be info.magnolia.ui.framework.tools.ToolsSubApp or a subclass.ToolsSubApp implements a subapp with several tools.

   tools

required

Map of ToolDefinition.

Tools are defined by ToolDefinition .

(See below for more details concerning tool definition.)

Example of an app with a tools subapp

Here is a complete example of a YAML based app which contains a tools subapp.

 appClass: info.magnolia.ui.framework.app.BaseApp
label: Sample Tools
icon: icon-development-app
subApps:
  main:
    class: info.magnolia.ui.framework.tools.ToolsSubAppDescriptor
    subAppClass: info.magnolia.ui.framework.tools.ToolsSubApp
    tools:
      "dashboard":
        presenterClass: info.magnolia.documentation.apps.toolssubapp.presenters.DashboardToolPresenter
      "i18n":
        class: info.magnolia.ui.framework.tools.FormToolDefinition
        actions:
          reloadTranslations:
            implementationClass: info.magnolia.documentation.apps.toolssubapp.actions.ReloadTranslationsAction
      "helloworld":
        class: info.magnolia.ui.framework.tools.FormToolDefinition
        presenterClass: info.magnolia.documentation.apps.toolssubapp.presenters.HelloWorldPresenter
        description: This is the hello world example for configured tools
        form:
          label: HWP
          tabs:
            - name: mainTab
              fields:
                - name: name
                  class: info.magnolia.ui.form.field.definition.TextFieldDefinition
                  required: true
        actions:
          commit:
            implementationClass: info.magnolia.documentation.apps.toolssubapp.actions.SayHelloAction
          reset:
            implementationClass: info.magnolia.documentation.apps.toolssubapp.actions.ResetFormAction

Node nameValue

 hello-tools-app

-

 appClass

info.magnolia.ui.framework.app.BaseApp

 label

Sample Tools

 icon

icon-development-app

 name

hello-tools-app

 subApps

 -

 main

 -

 class

info.magnolia.ui.framework.tools.ToolsSubAppDescriptor

 subAppClass

info.magnolia.ui.framework.tools.ToolsSubApp

 tools

-

 dashboard

 -

 presenterClass

info.magnolia.documentation.apps.toolssubapp.presenters.DashboardToolPresenter

 i18n

 -

 class

info.magnolia.ui.framework.tools.FormToolDefinition

 actions

-

 helloworld

 -

 class

info.magnolia.ui.framework.tools.FormToolDefinition

 presenterClass

info.magnolia.documentation.apps.toolssubapp.presenters.HelloWorldPresenter

 description

This is the hello world example for configured tools

 form

-

 actions

-

Note that this example requires Java 1.8 or higher to run. You can download the .jar file here: documentation . See Installing a module for help.

Properties:

<subapp name>

required

Subapp node name. This is the internal ID of the subapp. In this example it is main.

class

required

For a tools subapp must be info.magnolia.ui.framework.tools.ToolsSubAppDescriptor or a subclass.

ToolsSubAppDescriptor defines a subapp with several tools.

subAppClass

required

For a tools subapp must be info.magnolia.ui.framework.tools.ToolsSubApp or a subclass.ToolsSubApp implements a subapp with several tools.

   tools

required

Map of ToolDefinition.

Tools are defined by ToolDefinition (where you may have to define the presenter class that implements ToolPresenter ).

name

required

Name of the tool. In this example, there are three tools named dashboard, i18n and helloworld .

class

optional, default is info.magnolia.ui.framework.tools.ToolDefinition

presenterClass

required

Must implement ToolPresenter .

This example displays as follows in the Magnolia interface:

Tool definition

A tool is a small functional block which exists within a tools subapp. Tools subapps may have one or several tools.

Each tool is defined by a ToolDefinition in which you have to define the presenter class that must implement ToolPresenter . The tool definition class is i18n-ized and comes with its own key generator class: ToolDefinitionKeyGenerator .

Tools usually have some custom Java code to implement the logic of the task you want it to accomplish. The logic can be in a presenter class or in an action class depending on the type of the tool definition class.

Tool examples

Each tool defined in the tools subapp example above is different:

Dashboard tool

By using a custom presenter class (and View or ViewAdapter), you get the full freedom to build a Vaadin UI.

The dashboard tool uses the default configuration class (property class), and therefore must provide a presenterClass. This is the YAML excerpt for this tool definition from the example:

      "dashboard":
        presenterClass: info.magnolia.documentation.apps.toolssubapp.presenters.DashboardToolPresenter
This is the custom presenter:


 Click here to see DashboardToolPresenter

info.magnolia.documentation.apps.toolssubapp.presenters.DashboardToolPresenter
package info.magnolia.documentation.apps.toolssubapp.presenters;
 
import info.magnolia.stats.JCRStats;
import info.magnolia.ui.api.view.View;
import info.magnolia.ui.framework.tools.ToolDefinition;
import info.magnolia.ui.framework.tools.ToolPresenter;
 
import java.text.SimpleDateFormat;
import java.util.Date;
 
import com.vaadin.event.UIEvents;
import com.vaadin.ui.FormLayout;
import com.vaadin.ui.Label;
import com.vaadin.ui.UI;
 
/**
 * A simple {@link ToolPresenter} implementation.
 */
public class DashboardToolPresenter implements ToolPresenter<ToolDefinition, View> {
 
    @Override
    public View start(ToolDefinition toolDefinition) {
        return (View) () -> {
            Label label = new Label(getSessionCount());
            label.setCaption("Active JCR sessions");
 
            UIEvents.PollListener pollListener = event -> label.setValue(getSessionCount());
            UI.getCurrent().addPollListener(pollListener);
            label.addDetachListener(event -> {
                UI.getCurrent().setPollInterval(-1);
                UI.getCurrent().removePollListener(pollListener);
            });
            UI.getCurrent().setPollInterval(9000);
 
            return new FormLayout(label);
        };
    }
 
    private String getSessionCount() {
        int sessionCount = JCRStats.getInstance().getSessionCount();
        String currentDate = SimpleDateFormat.getDateTimeInstance().format(new Date());
        return String.format("%d (last updated %s)", sessionCount, currentDate);
    }
}

Note:


  • The presenter implements #start which returns the View.
  • The method uses Lambda expression. This is why the example requires Java 8 or higher.

i18n tool

The i18n tool has the value info.magnolia.ui.framework.tools.FormToolDefinition set for the class property.  FormToolDefinition (or actually its implementation  ConfiguredFormToolDefinition ) provides a default presenterClass.

By using FormToolDefinition, you can provide some action configurations only; no need to write presentation code. Implement the logic to execute on the custom action class.

FormToolDefinition also requires a list of action classes. This tool example provides one custom action: info.magnolia.documentation.apps.toolssubapp.actions.ReloadTranslationsAction.

 Click here to see ReloadTranslationsAction.java

ReloadTranslationsAction.java
public class ReloadTranslationsAction implements Action {
 
    private final TranslationService translationService;
    private final UiContext uiContext;
    private final ActionDefinition actionDefinition;
 
    @Inject
    public ReloadTranslationsAction(TranslationService translationService, UiContext uiContext, ActionDefinition actionDefinition) {
        this.translationService = translationService;
        this.uiContext = uiContext;
        this.actionDefinition = actionDefinition;
    }
 
    @Override
    public void execute() throws ActionExecutionException {
        translationService.reloadMessageBundles();
        uiContext.openNotification(MessageStyleTypeEnum.INFO, true, actionDefinition.getSuccessMessage());
    }
}

Note:


  • You should inject the definition class in the constructor.
  • You can inject other components such as TranslationService and UiContext (lines 7-8).

Helloworld tool

Like i18n, the helloworld tool also has the value info.magnolia.ui.framework.tools.FormToolDefinition set for the class property. Like the dashboard tool, helloworld provides a custom presenterClass : info.magnolia.documentation.apps.toolssubapp.presenters.HelloWorldPresenter .

HelloWorldPresenter extends info.magnolia.ui.framework.tools.FormToolPresenter (which is the default presenterClass for FormToolDefinition ).

 Click here to see HelloWorldPresenter.java

HelloWorldPresenter.java
public class HelloWorldPresenter extends FormToolPresenter {
 
    @Inject
    public HelloWorldPresenter(FormToolView view, FormBuilder formBuilder, FormToolActionExecutor actionExecutor) {
        super(view, formBuilder, actionExecutor);
    }
 
    @Override
    protected Item getItem() {
        return new BeanItem<>(new HelloBean());
    }
 
    /**
     * A simple static inner class with the property 'name'.
     */
    public static class HelloBean {
        private String name;
 
        public String getName() {
            return name;
        }
 
        public void setName(String name) {
            this.name = name;
        }
    }
}

Other tool implementation examples

Magnolia provides the following implementations based on FormToolPresenter in the Security app that you can use for inspiration:

  • permission/PermissionToolPresenter
  • group/GroupMemberPresenter
  • RoleAssignmentPresenter

You typically have to implement your own presenterClass to fulfill your requirements. However, extending FormToolPresenter may be a good starting point.