ToolsSubApp descriptor - 5 UI
Deprecated
|
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).
ToolsSubApp definition
subApps:
main:
class: info.magnolia.ui.framework.tools.ToolsSubAppDescriptor
subAppClass: info.magnolia.ui.framework.tools.ToolsSubApp
tools:<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.
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|
Note that this example requires Java 1.8 or higher to run. You can download the .jar file at info.magnolia.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 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:
info.magnolia.documentation.apps.toolssubapp.presenters.DashboardToolPresenter
NOTE:
-
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.
ReloadTranslationsAction.java
|
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).
HelloWorldPresenter.java
Other tool implementation examples
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.