Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

Action definitions configure actions in the UI. The action has a name which is the name of the definition content node, for example addContact below. The action is identified by this name within a certain scope such as within a subapp. Actions have an action definition class that implements the ActionDefinition  interface. The definition class allows you to supply additional parameters to the action and call further classes to execute logic.

Here is the addContact action from the Contacts app. A user can execute the action in the action bar or in the action popup. When the action is executed, the detail subapp is launched.

Node nameValue

 modules

 

 contacts

 

 apps

 

 contacts

 

 subApps

 

 browser

 

 actions

 

 addContact

 

 availability

 

 appName

contacts

 class

info.magnolia.ui.contentapp.detail.action.CreateItemActionDefinition

 icon

icon-add-item

 label

New contact

 nodeType

mgnl:contact

 subAppId

detail

Action properties:

  • availability: Defines whether the action is permitted on the selected item. Optional.

  • appName: Optional. Name of the app to launch when executing this action. This property works together with the subAppId property. They tell where the action takes place. For example, the addContact action takes place in the detail subapp of the contacts app. The detail subapp displays a form that allows the user to fill in the contact's details. Set the property value to the app name given in app configuration.
  • class : Mandatory. Action definition class that reads the configuration properties and can supply additional parameters to the action. The class must implement the  ActionDefinition  interface. Set the value to a fully-qualified class name.
  • dialogName : Optional. Dialog to open when the action is executed. A dialog is an alternative to editing items in an editor. Identify the dialog using syntax  <app name>:<dialog name> , for example  contacts:folder .
  • icon: Optional. CSS class that identifies an icon font used on the app tile. For available names see Icons.
  • implementationClass: Optional. In an action, the implementation class executes the action. Typically, a default implementation class is already hard-coded in the definition class. You only need to add this property if you want to override the default implementation with your own. For example, you might want to perform some extra validation on a saved value.
  • label: Optional. Label displayed to users in the action bar or context menu.
  • nodeType: Optional. Type of node this action creates or operates on. This property is needed if the action calls a dialog, such as in the Security app where users are edited by a dialog, not by a detail supapp. The property tells the dialog what node type it should operate on. When the action is executed in a detail app, however, the property is not needed because the /detail/editor/nodeType/name property already defines the node type.
  • modifiedOnly: Publishes only nodes that are modified  or never published . Excludes nodes that are already published . Use this property to make recursive publishing faster as it eliminates already-published nodes. Default value is false(warning) Magnolia 5.3.4+
  • subAppId : Optional. Name of the subapp to open when executing this action.

Action definition classes

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

ClassDescription
info.magnolia.ui.form.action.SaveFormActionDefinitionSaves a form.
info.magnolia.ui.form.action.CancelFormActionDefinitionCancels a form.
info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinitionSaves a dialog.
info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinitionCancels a dialog.
info.magnolia.ui.contentapp.movedialog.action.OpenMoveDialogActionDefinitionOpens a dialog for moving an item and its children. A standard move dialog is provided.
info.magnolia.ui.contentapp.detail.action.EditItemActionDefinitionOpens an item for editing.

info.magnolia.ui.framework.action.OpenCreateDialogActionDefinition

Opens a dialog for creating an item. Provide the dialog using the dialogName property.
info.magnolia.ui.framework.action.OpenEditDialogActionDefinitionOpens a dialog for editing an item. Provide the dialog using the dialogName property.
info.magnolia.ui.framework.action.DeleteItemActionDefinitionDeletes an item.
info.magnolia.ui.framework.action.ActivationActionDefinitionActivates an item. By default, performs a non-recursive activation.
info.magnolia.ui.framework.action.DeactivationActionDefinitionDeactivates an item.
info.magnolia.ui.framework.action.ExportActionDefinitionExports an item and its children into XML.
info.magnolia.ui.framework.action.DownloadBinaryActionDefinitionDownloads a binary node such as an image.
info.magnolia.ui.api.action.CommandActionDefinitionDelegates the action to a named command. Provide the command in the command property.

Reusing an action

Reuse the existing Magnolia actions in your own app. Many actions are so basic that you can just copy the action definition. Some actions have their own properties. You may need to set them for the action to work.

Example: The DownloadBinaryActionDefinition allows you to download a binary node from the repository to your computer. This action is available in the Assets app by default where the user can download images from the dam workspace. In this example we use the same action in the Contacts app to download a contact photo.

Action definition:

Node nameValue

 downloadContactPhoto

 

 binaryNodeName

photo

 class

info.magnolia.ui.framework.action.DownloadBinaryActionDefinition

 icon

icon-download

 label

Download photo

Properties:

  • binaryNodeName: Subnode that holds the binary property. Export a content item into XML to find the name, see example below. Default is binaryNodeName.
  • dataProperty: Property that holds the binary data, usually right below the binary node in the exported XML. Default is jcr:data.
  • fileNameProperty: Property that holds the file name of the binary. Default is fileName.
  • extensionProperty: Property that holds the file name extension of the binary. Default is extension.

Contact exported to XML, helps you find the property names:

contacts.vvangogh.xml
<sv:node sv:name="photo">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>mgnl:resource</sv:value>
  </sv:property>
  <sv:property sv:name="jcr:uuid" sv:type="String">
    <sv:value>ed5f5ed0-26fc-4c43-8d63-21aca30ca151</sv:value>
  </sv:property>
  <sv:property sv:name="extension" sv:type="String">
    <sv:value>jpg</sv:value>
  </sv:property>
  <sv:property sv:name="fileName" sv:type="String">
    <sv:value>vangogh</sv:value>
  </sv:property>
  <sv:property sv:name="height" sv:type="Long">
    <sv:value>479</sv:value>
  </sv:property>
  <sv:property sv:name="jcr:data" sv:type="Binary">
    <sv:value>/9j/4AAQSkZJRgABAQEASABIAAD

Command actions

While actions usually trigger activity within the same app, they can also trigger activity elsewhere by executing commands. Commands can perform duties within Magnolia or connect to external resources. Use the info.magnolia.ui.api.action.CommandActionDefinition class when you want to execute a command. A command may be a long-running process. Additional properties allow you to control whether command actions are run asynchronously.

Here's an example of a publish action that executes the activate command:

Node nameValue

 modules

 

 workflow

 

 generic

 

 actions

 

 publish

 

 catalog

workflow

 class

info.magnolia.module.workflow.action.WorkflowPublicationActionDefinition

 command

activate

 icon

icon-publish

Command action properties:

  • command: An action can trigger a command. Commands are used to perform longer sequences of tasks. For example, the activate command publishes content from the author instance to public instances and versions the content. Set the value to a command name.
  • asynchronous: Optional. Runs a command asynchronously in the background. This is useful for long-running commands. An asynchronous process doesn't block the UI and the user can continue with their work. To run a command asynchronously, set the property to true. Default is false. See also delay and parallel below.

  • catalog: Optional. Name of the catalog where the command resides. See command below. Needed only you implement a command that has the same name as an existing command such as activate.
  • delay: Optional. Number of seconds to wait before invoking a command. Used together with the  asynchronous  property. Default is 1 second.

  • parallel: Optional. Used together with the asynchronous property. Defines whether starting multiple instances of the same action in parallel is allowed. Useful for preventing the user from starting several long-running commands. Default is true, allowing parallel actions. When you set the property to false the system will display an error when the user attempts to run the same action again while the first action is still running.

Action availability

Action availability defines whether the action is permitted on the selected item. For example, the addCategory action below is permitted when:

  • The selected item is a category, meaning you can create subcategories.
  • The selected item is a folder.
  • At the root level of the workspace, meaning you can create a category without selecting an item.
  • The selected item is not marked for deletion.

(warning) Magnolia 5.3+: Starting with Magnolia 5.3 you can add multiple availability rule classes. See the example below. The rules parent node contains subnodes, one for each rule. The rules are combined with a logical AND operator. Each rule must have the implementationClass property which points directly to the rule class (no more definition class).

Node nameValue

 actions

 

 addCategory

 

 availability

 

 nodeTypes

 

 category

mgnl:category

 folder

mgnl:folder

 root

true

 rules

 

 notDeletedRule

 

 implementationClass

info.magnolia.ui.api.availability.IsNotDeletedRule

 anotherRule

 

 implementationClass

com.your.customapp.app.action.availability.AnotherAvailabilityRule

Properties

  • availability
    • access: Action is available if the current user has one of the listed roles.
      • roles
        • <role>: Name of the role that is permitted to execute the action.
    • nodes: Action is available if the selected item is a node.
    • nodeTypes:Action is available if the selected item is one of the node types listed.
      • <node type>: A valid node type such as mgnl:folder.
    • rules: Action is available if the selected item(s) match for every availability rule class
      • <ruleNodeName>: give the node a name which reflects the rule-class
        • implementationClass : the class name of the rule availability class; class must implement info.magnolia.ui.api.availability.AvailabilityRule (usually just extending info.magnolia.ui.api.availability.AbstractAvailabilityRule)
    • root: Action is available at the workspace root level if true.
    • properties: Action is available if the selected item is a property.
    • multiple: Boolean property that enables and disables multiselection. Default is false. Available when the action class extends  AbstractMultiItemAction . 
    • writePermissionRequired: Optional. Set to true if the action requires write permission on the currently selected node. The action will be disabled if the user doesn't have write permission. Default is false

(warning) Magnolia 5.2.x and earlier:

Node nameValue

 actions

 

 addCategory

 

 availability

 

 nodeTypes

 

 category

mgnl:category

 folder

mgnl:folder

 root

true

 ruleClass

info.magnolia.ui.api.availability.IsNotDeletedRule

Properties

  • availability
    • access: Action is available if the current user has one of the listed roles.
      • roles
        • <role>: Name of the  role  that is permitted to execute the action.
    • nodes: Action is available if the selected item is a node.
    • nodeTypes:Action is available if the selected item is one of the node types listed.
      • <node type>: A valid node type such as mgnl:folder.
    • ruleClass: Class that contains custom logic to check if the action is permitted on the selected item. A common example is info.magnolia.ui.api.availability.IsNotDeletedRule which checks that the item is not marked for deletion. Your custom class must extend  AbstractAvailabilityRule .
    • root: Action is available at the workspace root level if true.
    • properties: Action is available if the selected item is a property.
    • multiple: Boolean property that enables and disables multiselection. Default is false. Available when the action class extends  AbstractMultiItemAction . 

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, then action availability is checked for each action in the section.

Actions on multiple items

Action availability defines whether an action can be executed on multiple items. Delete, move, export, publish and unpublish are examples of actions that can be executed on multiple items. Actions that open dialogs cannot handle multiple items. By default, the delete action is available for multiple items in all content apps.

In this example the  activate  action supports multiple items:

Node nameValue

 actions

 

 activate

 

 availability

 

 multiple

true

 catalog

versioned

 class

info.magnolia.ui.framework.action.ActivationActionDefinition

 command

 activate

 icon

 icon-publish

Properties:

multiple

optional, default is false

Defines whether the action is available for multiple items.

To do a more detailed availability check, such as to verify that all the items are on 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 a correct order to avoid exceptions, or handle such 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.

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 user interface 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 does not complete in the next five seconds, the system notifies the user that the action will take a while to complete. The execution continues in the background while the user can work on something else. The system informs the user when the action succeeds or fails. In case of failure a message in the Pulse  may refer to a log file for more detail.

(warning) Magnolia 5.3+. Publish recursively and Delete action run asynchronously by default. These actions involve versioning of content and can be time consuming.