ToolsSubApp descriptor has been deprecated since Magnolia 6.0. It is
part of the Magnolia 5 UI framework.
There is no corresponding implementation in the Magnolia 6 UI
framework.
The tools subapp is a special type of
subapp
that contains a list of tools. A tool is a small functional block that
is defined by 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).
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 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:
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:
The presenter implements #start which returns the View.
The method uses
Lambda
expression. This is why the example requires Java 8 or higher. See the Certified stack page to
confirm the latest supported Java version.
i18n tool
The i18n tool has the value
info.magnolia.ui.framework.tools.FormToolDefinition set for the
class property.
FormToolDefinition (or 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.
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).
Magnolia provides the following implementations based on
FormToolPresenter in the
Security app that you can use for
inspiration:
PermissionToolPresenter
GroupMemberPresenter
RoleAssignmentPresenter
You typically have to implement your own presenterClass to fulfill your
requirements. However, extending FormToolPresenter may be a good
starting point.