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 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

Property Description

<action name>

required

Name of the action. The name is used in action bar definition.

     class

required (unless $type is used)

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.

     $type

You can use this as a shortcut for class if the definition class is annotated with info.magnolia.ui.api.action.ActionType. The proper value is defined by the annotation.

Example class annotation
@ActionType("addNodeAction")
public class AddNodeActionDefinition extends ConfiguredActionDefinition {
...
}

To use the $type property in YAML, see General actions.

     label

required

Label displayed to users in the action bar or context menu.

     implementationClass

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.

     icon

optional

CSS class that identifies an icon used for the action. For available names, see Icons.

     availability

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

openDialogAction

Opens a dialog. Uses the dialogId property.

info.magnolia.ui.editor.FormView is automatically populated whenever OpenDialogActionDefinition is configured. This can trigger exceptions in fields with defined defaultValue. To disable this behavior, set the populate property in OpenDialogActionDefinition to false. Here is an openDialogAction definition from the Resource Files app:

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

ConfirmationActionDefinition

confirmationAction

Opens a dialog to confirm a previous action.

deleteNodesConfirmationAction

Opens a dialog to confirm deleting an item.

chooseAction

Selects an item in a dialog.

moveAction

Moves an item in a dialog.

commitAction

Saves and closes a dialog.

closeAction

Cancels and closes a dialog.

openDetailSubappAction

Opens the detail subapp.

SaveDetailSubAppActionDefinition

N/A

Saves and closes the detail subapp and selects the edited item in the browser (useful when creating new items).

OpenLocationActionDefinition

N/A

Opens a location in Admincentral.

showVersionAction

Shows the selected version of an item.

restoreJcrVersionAction

Restores the selected version of an item and its children.

showPreviousJcrVersionAction

Shows the previous version of an item.

restorePreviousJcrVersionAction

Restores the previous version of an item and its children.

AddNodeActionDefinition

addNodeAction

Adds an item.

DuplicateNodeActionDefinition

duplicateNodeAction

Duplicates an item.

copyContentAction

Copies an item.

cutContentAction

Cuts an item.

pasteContentAction

Pastes an item.

chainedAction

Defines a chain of actions.

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

Property Description

<action name>

required

Name of the action.

command

required

Name of the command.

catalog

optional, default is default

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 publish.

asynchronous

optional, default is false

Runs a command asynchronously in the background, which is useful for long-running actions. To run a command asynchronously, set the property to true.

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 markAsDeleted command.

JcrExportActionDefinition

exportAction

Exports an item and its children to XML or YAML.

JcrImportActionDefinition

importAction

Imports an XML or YAML file. Uses the import command.

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

Property Description

<action name>

required

Name of the action.

availability

optional

Node containing the availability configuration.

access

optional

Action is available if the current user has one of the listed roles.

roles

required

Node containing a list of roles.

<role>

required

Name of the role that is permitted to execute the action. Add one property for each role.

nodeTypes

optional

Action is available if the selected item belongs to one of the listed node types.

<node type>

required

Valid node type such as mgnl:folder.

rules

optional

Action is available if the selected item matches every availability rule class.

<ruleNodeName>

required

Gives the node a name that describes the rule class.

class

required (unless $type is used)

Action availability definition class. The class must implement the AvailabilityDefinition interface. Set the value to the fully qualified class name.

$type

You can use this as a shortcut for class if the definition class is annotated with info.magnolia.ui.api.availability.AvailabilityRuleType. The proper value is defined by the annotation.

implementationClass

required

Class implementing info.magnolia.ui.availability.rule.AvailabilityRule (you can extend info.magnolia.ui.availability.rule.AbstractAvailabilityRule). 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.

nodes

optional, default is true

Action is available if the selected item is a node.

root

optional, default is false

Action is available at the workspace root level if true.

properties

optional, default is false

Action is available if the selected item is a property.

multiple

optional, default is false

Defines whether the action is available for multiple items.

For more information, see Actions on multiple items.

writePermissionRequired

optional, default is false

Set to true if the action requires write permission on the currently selected node. The action will be disabled if the user does not have write permission.

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.

JcrDepthRuleDefinition

jcrDepthRule

Returns true if the item is within the specified depth range.

IsValidFormRuleDefinition

N/A

Returns true if the form where the action is defined is valid.

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.

Feedback