Action definition

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.

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.  Magnolia 5.3.4+
• subAppId : Optional. Name of the subapp to open when executing this action.

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

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

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. 

 Magnolia 5.2.x and earlier:

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 . 

In this example the  activate  action supports multiple items:

Properties:

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.