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 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:content availability: root: true nodeTypes: - mgnl:content
You can use the following properties for all actions.
General action properties
<action name> | 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 ActionDefinition interface. Set the value to the fully qualified class name. |
| You can use this as a shortcut for $type property in YAML, see General actions. |
| 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. For more information, see Action availability. |
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 ActionDefinition interface.
class | $type | Description |
---|---|---|
OpenDialogActionDefinition | openDialogAction | Opens a dialog. Uses the addFile: icon: icon-add-file $type: openDialogAction populate: false dialogId: resources-app:addFile availability: root: true rules: IsResourceFolderRule: &isResourceFolder implementationClass: info.magnolia.resources.app.availability.IsResourceFolderRule |
| confirmationAction | Opens a dialog to confirm a previous action. |
DeleteNodesConfirmationActionDefinition | deleteNodesConfirmationAction | Opens a dialog to confirm deleting an item. |
ChooseActionDefinition | chooseAction | Selects an item in a dialog. |
MoveActionDefinition | moveAction | Moves an item in a dialog. |
CommitActionDefinition | commitAction | Saves and closes a dialog. |
CloseActionDefinition | closeAction | Cancels and closes a dialog. |
OpenDetailSubappActionDefinition | openDetailSubappAction | Opens the detail subapp. |
| N/A | Opens a location in Admincentral. |
ShowVersionActionDefinition | showVersionAction | Shows the selected version of an item. |
RestoreJcrVersionActionDefinition | restoreJcrVersionAction | Restores the selected version of an item and its children. |
ShowPreviousJcrVersionActionDefinition | showPreviousJcrVersionAction | Shows the previous version of an item. |
RestorePreviousJcrVersionActionDefinition | restorePreviousJcrVersionAction | Restores the previous version of an item and its children. |
| addNodeAction | Adds an item. |
| duplicateNodeAction | Duplicates an item. |
CopyContentActionDefinition | copyContentAction | Copies an item. |
CutContentActionDefinition | cutContentAction | Cuts an item. |
PasteContentActionDefinition | pasteContentAction | Pastes an item. |
ChainedActionDefinition | chainedAction | Defines a chain of actions. |
SetDataFilterActionDefinition | N/A | Sets a data filter. |
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 CommandActionDefinition. To implement your own command, create an action definition class that extends CommandActionDefinition and an action implementation class that extends 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 publish
command action 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
<action name> | 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 For more information, see Asynchronous actions. |
Some command action definition classes support additional properties such as recursive
, modifiedOnly
and parentNodeTypeOnly
.
Command action definition classes
You can use these common classes in command action definition. They all implement the ActionDefinition interface.
class | $type | Description |
---|---|---|
JcrCommandActionDefinition | jcrCommandAction | Delegates the action to a named command. |
MarkAsDeletedCommandActionDefinition | markAsDeletedAction | Marks an item as deleted. Uses the |
JcrExportActionDefinition | exportAction | Exports an item and its children to XML or YAML. |
JcrImportActionDefinition | importAction | 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
Action availability properties
<action name> | 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 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 |
---|---|---|
JcrNodeRuleDefinition | N/A | Returns true if the item is a node. |
JcrNodeTypeRuleDefinition | N/A | Returns true if the item is a node of any of the listed types. |
JcrIsDeletedRuleDefinition | jcrIsDeletedRule | Returns true if the item is a node of the mgnl:deleted mixin type. |
JcrPropertyRuleDefinition | N/A | Returns true if the item is a property. |
CanCopyContentRuleDefinition | canCopyContentRule | Returns true if the item can be copied. |
CanPasteContentRuleDefinition | canPasteContentRule | Returns true if the item can be pasted. |
CanMoveRuleDefinition | N/A | Returns true if the item can be moved. |
JcrPublishableRuleDefinition | jcrPublishableRule | Returns true if the item can be published. |
JcrPublishedRuleDefinition | jcrPublishedRule | Returns true if the item is published. |
JcrHasChildrenRuleDefinition | jcrHasChildrenRule | Returns true if the item has child nodes. |
JcrHasVersionsRuleDefinition | jcrHasVersionsRule | Returns true if the item has versions. |
| jcrDepthRule | Returns true if the item is within the specified depth range. |
AccessGrantedRuleDefinition | N/A | Returns true if access can be granted to the item. |
MultipleItemsRuleDefinition | N/A | Returns true if the action can be applied to multiple items. |
JcrRootRuleDefinition | N/A | Returns true if the action is at the workspace root level. |
JcrWritePermissionRuleDefinition | N/A | Returns true if the user has write permission for the item. |
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 publish
command action 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.