Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
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 name | Value |
---|---|
subApps | |
tools | |
class | info.magnolia.ui.framework.tools.ToolsSubAppDescriptor |
subAppClass | info.magnolia.ui.framework.tools.ToolsSubApp |
| required Subapp node name. This is the internal ID of the subapp. In this example it is |
| required For a tools subapp must be ToolsSubAppDescriptor defines a subapp with several tools. |
| required For a tools subapp must be |
| 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 name | Value |
---|---|
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:
| required Subapp node name. This is the internal ID of the subapp. In this example it is |
| required For a tools subapp must be ToolsSubAppDescriptor defines a subapp with several tools. |
| required For a tools subapp must be |
| required Map of ToolDefinition. Tools are defined by ToolDefinition (where you may have to define the presenter class that implements |
| required Name of the tool. In this example, there are three tools named |
| optional, default is |
| 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:This is the custom presenter:
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
.
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
).
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.