Page tree
Skip to end of metadata
Go to start of metadata

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.

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 on 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, subAppNamedialogId and nodeType.

General action definition classes

You can use these common classes in general action definition. They all implement the ActionDefinition interface.

class$typeDescription

OpenDialogActionDefinition

openDialogAction

Opens a dialog. Uses the dialogId property.

(info) info.magnolia.ui.editor.FormView is automatically populated whenever OpenDialogActionDefinition is configured. This can trigger exceptions in some cases where there is no initial value to populate the form with. To disable this default behavior, you can set the populate property to false in YAML. 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

confirmationActionOpens a dialog to confirm a previous action.

DeleteNodesConfirmationActionDefinition

deleteNodesConfirmationActionOpens a dialog to confirm deleting an item.

ChooseActionDefinition

chooseActionSelects an item in a dialog.

MoveActionDefinition

moveActionMoves an item in a dialog.

CommitActionDefinition

commitActionSaves and closes a dialog.

CloseActionDefinition

closeActionCancels and closes a dialog.

OpenDetailSubappActionDefinition

openDetailSubappActionOpens the detail subapp.

OpenLocationActionDefinition

N/AOpens a location in Admincentral.

ShowVersionActionDefinition

showVersionActionShows the selected version of an item.

RestoreJcrVersionActionDefinition

restoreJcrVersionActionRestores the selected version of an item and its children.

ShowPreviousJcrVersionActionDefinition

showPreviousJcrVersionActionShows the previous version of an item.

RestorePreviousJcrVersionActionDefinition

restorePreviousJcrVersionActionRestores the previous version of an item and its children.

AddNodeActionDefinition

addNodeActionAdds an item.

DuplicateNodeActionDefinition

duplicateNodeActionDuplicates an item.

CopyContentActionDefinition

copyContentActionCopies an item.

CutContentActionDefinition

cutContentActionCuts an item.

PasteContentActionDefinition

pasteContentActionPastes an item.

ChainedActionDefinition

chainedActionDefines a chain of actions.

SetDataFilterActionDefinition

N/ASets 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.

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

JcrCommandActionDefinition

jcrCommandActionDelegates the action to a named command.

MarkAsDeletedCommandActionDefinition

markAsDeletedAction

Marks an item as deleted. Uses the markAsDeleted command.

JcrExportActionDefinition

exportActionExports 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

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

JcrNodeRuleDefinition

N/AReturns true if the item is a node.

JcrNodeTypeRuleDefinition

N/AReturns true if the item is a node of any of the listed types.

JcrIsDeletedRuleDefinition

jcrIsDeletedRuleReturns true if the item is a node of the mgnl:deleted mixin type.

JcrPropertyRuleDefinition

N/AReturns true if the item is a property.

IsSystemPropertyDefinition

isSystemPropertyRuleReturns true if the item is a system property.

CanCopyContentRuleDefinition

canCopyContentRuleReturns true if the item can be copied.

CanPasteContentRuleDefinition

canPasteContentRuleReturns true if the item can be pasted.

CanMoveRuleDefinition

N/AReturns true if the item can be moved.

JcrPublishableRuleDefinition

jcrPublishableRuleReturns true if the item can be published.

JcrPublishedRuleDefinition

jcrPublishedRuleReturns true if the item is published.

JcrHasChildrenRuleDefinition

jcrHasChildrenRuleReturns true if the item has child nodes.

JcrHasVersionsRuleDefinition

jcrHasVersionsRuleReturns true if the item has versions.

AccessGrantedRuleDefinition

N/AReturns true if access can be granted to the item.

MultipleItemsRuleDefinition

N/AReturns true if the action can be applied to multiple items.

JcrRootRuleDefinition

N/AReturns true if the action is at the workspace root level.

JcrWritePermissionRuleDefinition

N/AReturns 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.

  • No labels