Action definition
Action definitions configure actions in the UI. They are used in apps, forms and dialogs. The action name is the definition content node name.
Each action has an action definition class that implements the info.magnolia.ui.api.action.ActionDefinition interface. Some definition classes allow for additional properties and call more classes to execute logic.
You can reuse existing Magnolia actions in your own app. Many actions are so basic that you can just copy their definitions. For actions that have their own properties, you may need to set the properties for the actions to work. |
These action definitions are part of the Magnolia 6 UI framework. If you work with the Magnolia 5 UI framework, see Action definition for Magnolia 5 UI instead. |
General actions
Here is an addNodeAction
definition. A user can execute the action in
the action bar or the action popup.
subApps:
browser:
class: info.magnolia.ui.contentapp.configuration.BrowserDescriptor
actions:
addFolder:
$type: addNodeAction
icon: icon-add-folder
nodeType: mgnl:folder
availability:
root: true
nodeTypes:
- mgnl:folder
You can use the following properties for all actions.
General action properties
Property | Description | ||
---|---|---|---|
|
required Name of the action. The name is used in action bar definition. |
||
|
required (unless Action definition class that reads the configuration properties and can supply additional properties to the action. The class must implement the info.magnolia.ui.api.action.ActionDefinition interface. Set the value to the fully qualified class name. |
||
|
You can use this as a shortcut for Example class annotation
To use the |
||
|
required Label displayed to users in the action bar or context menu. |
||
|
required Implementation class that executes the action. A default implementation class is typically hard-coded in the definition class. You only need to add this property if you want to override the default implementation. |
||
|
optional CSS class that identifies an icon used for the action. For available names, see Icons. |
||
|
optional Defines whether the action is permitted on the selected item.
|
Some action definition classes
support additional properties such as appName , subAppName ,
dialogId and nodeType .
|
General action definition classes
You can use these common classes in general action definition. They all implement the info.magnolia.ui.api.action.ActionDefinition interface.
class | $type | Description | ||
---|---|---|---|---|
info.magnolia.ui.dialog.actions.OpenDialogActionDefinition |
|
Opens a dialog. Uses the
|
||
info.magnolia.ui.contentapp.action.ConfirmationActionDefinition |
|
Opens a dialog to confirm a previous action. |
||
info.magnolia.ui.contentapp.action.DeleteNodesConfirmationActionDefinition |
|
Opens a dialog to confirm deleting an item. |
||
info.magnolia.ui.contentapp.action.ChooseActionDefinition |
|
Selects an item in a dialog. |
||
info.magnolia.ui.contentapp.action.MoveActionDefinition |
|
Moves an item in a dialog. |
||
info.magnolia.ui.contentapp.action.CommitActionDefinition |
|
Saves and closes a dialog. |
||
info.magnolia.ui.contentapp.action.CloseActionDefinition |
|
Cancels and closes a dialog. |
||
info.magnolia.ui.contentapp.action.OpenDetailSubappActionDefinition |
|
Opens the detail subapp. Different
|
||
info.magnolia.ui.contentapp.detail.action.SaveDetailSubAppActionDefinition |
N/A |
Saves and closes the detail subapp and selects the edited item in the browser (useful when creating new items). |
||
info.magnolia.ui.contentapp.action.OpenLocationActionDefinition |
N/A |
Opens a location in Admincentral. |
||
info.magnolia.ui.contentapp.action.ShowVersionActionDefinition |
|
Shows the selected version of an item. Different
|
||
info.magnolia.ui.contentapp.action.RestoreJcrVersionActionDefinition |
|
Restores the selected version of an item and its children. |
||
info.magnolia.ui.contentapp.action.ShowPreviousJcrVersionActionDefinition |
|
Shows the previous version of an item. |
||
info.magnolia.ui.contentapp.action.RestorePreviousJcrVersionActionDefinition |
|
Restores the previous version of an item and its children. |
||
info.magnolia.ui.contentapp.action.AddNodeActionDefinition |
|
Adds an item. |
||
info.magnolia.ui.contentapp.action.DuplicateNodeActionDefinition |
|
Duplicates an item. |
||
info.magnolia.ui.contentapp.action.clipboard.CopyContentActionDefinition |
|
Copies an item. |
||
info.magnolia.ui.contentapp.action.clipboard.CutContentActionDefinition |
|
Cuts an item. |
||
info.magnolia.ui.contentapp.action.clipboard.PasteContentActionDefinition |
|
Pastes an item. |
||
info.magnolia.ui.contentapp.action.ChainedActionDefinition |
|
Defines a chain of actions. |
||
info.magnolia.ui.contentapp.action.SetDataFilterActionDefinition |
N/A |
Sets a data filter. |
Custom commit actions
To access the inner fields of a complex field,
you can create CustomCommitAction
as an implementation class that extends CommitAction
:
public class CustomCommitAction<T> extends CommitAction<T> {
@Inject
public CustomCommitAction(CommitActionDefinition definition, CloseHandler closeHandler, ValueContext<T> valueContext, EditorView<T> form, Datasource<T> datasource, DatasourceObservation.Manual datasourceObservation) {
super(definition, closeHandler, valueContext, form, datasource, datasourceObservation);
}
@Override
protected void write() {
getForm().validate().stream()
.flatMap(binderValidationStatus -> binderValidationStatus.getBinder().getFields())
.filter(AbstractSingleSelect.class::isInstance)
.map(HasValue::getValue)
.filter(Option.class::isInstance)
.map(Option.class::cast)
.findFirst()
.ifPresent(switcherValue -> {
if ("foo".equals(switcherValue.getValue())) {
// processing the switcher value
}
});
}
public static class Definition extends CommitActionDefinition {
public Definition() {
setImplementationClass(CustomCommitAction.class);
}
}
}
Command actions
For more complicated tasks, an action can trigger a
command. For example, the publish
command
publishes content from the author instance to public instances and
versions the content.
Each command action used in the UI has its own action definition class that extends info.magnolia.ui.api.action.CommandActionDefinition. To implement your own command, create an action definition class that extends info.magnolia.ui.api.action.CommandActionDefinition and an action implementation class that extends info.magnolia.ui.contentapp.action.CommandAction.
Commands can perform tasks within Magnolia or connect to external resources. Commands may run for a long time; additional properties allow you to control whether command actions are run asynchronously without blocking the UI.
Here is a jcrCommandAction
definition from the
Magnolia
DAM JCR implementation.
browser:
actions:
activate:
icon: icon-publish
$type: jcrCommandAction
command: publish
catalog: versioned
You can use the following properties as well as general action properties for command actions.
Command action properties
Property | Description | ||
---|---|---|---|
|
required Name of the action. |
||
|
required Name of the command. |
||
|
optional, default is Name of the catalog where the
command resides. You only need this property if you implement a command
that has the same name as an existing command such as |
||
|
optional, default is Runs a command asynchronously in the background, which is useful for
long-running actions. To run a command asynchronously, set the property
to
|
Some command action definition classes support additional properties such as In the context of configuring publishing for changes only, you must declare
|
Command action definition classes
You can use these common classes in command action definition. They all implement the info.magnolia.ui.api.action.ActionDefinition interface.
class | $type | Description |
---|---|---|
info.magnolia.ui.contentapp.action.JcrCommandActionDefinition |
|
Delegates the action to a named command. |
info.magnolia.ui.contentapp.action.MarkAsDeletedCommandActionDefinition |
|
Marks an item as deleted. Uses the
|
info.magnolia.ui.contentapp.action.JcrExportActionDefinition |
|
Exports an item and its children to XML or YAML. |
info.magnolia.ui.contentapp.action.JcrImportActionDefinition |
|
Imports an XML or YAML file. Uses the |
Asynchronous actions
Setting the asynchronous
property to true
allows you to run a
command action asynchronously in the background. Use this feature for
long-running actions that would otherwise block the UI and prevent the
user from continuing their work.
When a user launches an asynchronous action, Magnolia starts to execute the action immediately. If the action is not completed within five seconds, the system will notify the user that the action will take a while to complete. The execution continues in the background while the user works on something else, and the system informs the user when the action succeeds or fails. In case of failure, a message in the Notifications app may refer to a log file for more details.
Recursive publish
and delete
actions run asynchronously by default.
Because these actions involve content versioning, they can be
time-consuming.
Action availability
Action availability defines whether the action is permitted on the selected item.
For example, the addNodeAction
definition below is permitted when:
-
The action is at the workspace root level (you can create a category without selecting an item).
-
The selected item is a category (you can create subcategories).
-
The selected item is a folder.
-
The selected item is not marked for deletion.
Action availability is different from action bar section availability. Section availability defines whether the actions configured within a section are displayed in the action bar. If the section is displayed, action availability will be checked for each action in the section. |
You can add multiple availability rule classes. The rules
parent
node contains subnodes, one for each rule. The rules are combined
with a logical AND
operator.
actions:
addCategory:
availability:
nodes: true
root: true
nodeTypes:
- mgnl:category
- mgnl:folder
rules:
- name: isNotDeletedRule
$type: jcrIsDeletedRule
negate: true
- name: anotherRule
class: com.your.customapp.app.action.availability.AnotherAvailabilityRuleDefinition
You can also restrict an action by role.
Here is an OpenPublicationDialogActionDefinition
that only the editor
and publisher
roles are permitted to execute.
actions:
activate: !override &activate
class: info.magnolia.module.workflow.action.OpenPublicationDialogActionDefinition
dialogName: workflow:publish
icon: icon-publish
catalog: website
command: activate
label: Request to Publish
availability:
writePermissionRequired: true
access:
roles:
editor: editor
publisher: publisher
rules:
IsPublishableRule:
implementationClass: info.magnolia.ui.framework.availability.IsPublishableRule
name: IsPublishableRule
Action availability properties
Property | Description |
---|---|
|
required Name of the action. |
|
optional Node containing the availability configuration. |
|
optional Action is available if the current user has one of the listed roles. |
|
required Node containing a list of roles. |
|
required Name of the role that is permitted to execute the action. Add one property for each role. |
|
optional Action is available if the selected item belongs to one of the listed node types. |
|
required Valid node type such as
|
|
optional Action is available if the selected item matches every availability rule class. |
|
required Gives the node a name that describes the rule class. |
|
required (unless Action availability definition class. The class must implement the info.magnolia.ui.api.availability.AvailabilityDefinition interface. Set the value to the fully qualified class name. |
|
You can use this as a shortcut for |
|
required Class implementing |
|
optional, default is Action is available if the selected item is a node. |
|
optional, default is Action is available at the workspace root level if |
|
optional, default is Action is available if the selected item is a property. |
|
optional, default is Defines whether the action is available for multiple items. For more information, see Actions on multiple items. |
|
optional, default is Set to |
Action availability definition classes
class | $type | Description | ||
---|---|---|---|---|
info.magnolia.ui.availability.rule.JcrNodeRuleDefinition |
N/A |
Returns |
||
info.magnolia.ui.availability.rule.JcrNodeTypeRuleDefinition |
N/A |
Returns |
||
info.magnolia.ui.availability.rule.JcrIsDeletedRuleDefinition |
|
Returns |
||
info.magnolia.ui.availability.rule.JcrPropertyRuleDefinition |
N/A |
Returns |
||
info.magnolia.ui.contentapp.action.clipboard.CanCopyContentRuleDefinition |
|
Returns |
||
info.magnolia.ui.contentapp.action.clipboard.CanPasteContentRuleDefinition |
|
Returns |
||
info.magnolia.ui.availability.rule.CanMoveRuleDefinition |
N/A |
Returns
|
||
info.magnolia.ui.availability.rule.JcrPublishableRuleDefinition |
|
Returns |
||
info.magnolia.ui.availability.rule.JcrPublishedRuleDefinition |
|
Returns |
||
info.magnolia.ui.availability.rule.JcrHasChildrenRuleDefinition |
|
Returns |
||
info.magnolia.ui.availability.rule.JcrHasVersionsRuleDefinition |
|
Returns |
||
info.magnolia.ui.availability.rule.JcrDepthRuleDefinition |
|
Returns |
||
info.magnolia.ui.availability.rule.IsValidFormRuleDefinition |
N/A |
Returns |
||
info.magnolia.ui.availability.rule.AccessGrantedRuleDefinition |
N/A |
Returns |
||
info.magnolia.ui.availability.rule.MultipleItemsRuleDefinition |
N/A |
Returns |
||
info.magnolia.ui.availability.rule.JcrRootRuleDefinition |
N/A |
Returns |
||
info.magnolia.ui.availability.rule.JcrWritePermissionRuleDefinition |
N/A |
Returns |
Actions on multiple items
Action availability defines whether an action can be executed on
multiple items. delete
, move
, publish
and unpublish
are examples
of actions that can be executed on multiple items.
Here is a jcrCommandAction
definition supporting multiple items.
actions:
activate:
catalog: versioned
$type: jcrCommandAction
command: publish
icon: icon-publish
availability:
multiple: true
For a more detailed availability check (such as verifying that all items are at the same level or have the same parent), use action availability rules.
When you program an action that supports multiple items, you are responsible for handling the items in the correct order and solving dependencies. For example, when deleting multiple nodes where one node is a child of another, delete the nodes in the correct order to avoid exceptions. An action is also responsible for informing the user about the result whether it has successfully processed all the items or failed on some of them.