Magnolia 5.5 reached end of life on November 15, 2019. 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. The action is identified by this name within a certain scope, such as within a subapp. 

Action definitions are used in apps, forms and dialogs. They are configured and used in the same way throughout the UI. Dialogs and forms typically require only save and cancel actions, which are simple configurations.

Action definition properties

Each actions has an action definition class that implements the ActionDefinition interface. Some definition classes allow for additional properties and call further classes to execute logic.

General actions

Example: addContact action definition in 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.

contacts/apps/contacts.yaml
subApps:
  browser:
    subAppClass: info.magnolia.ui.contentapp.browser.BrowserSubApp
    class: info.magnolia.ui.contentapp.browser.BrowserSubAppDescriptor
    actions:
      addContact:
        appName: contacts
        class: info.magnolia.ui.contentapp.detail.action.CreateItemActionDefinition
        subAppId: detail
        label: New contact
        nodeType: mgnl:contact
        icon: icon-add-item   
Node nameValue

 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

You can use these properties with all actions.

Properties:

<action name>The name of the action. The name is used in the Action bar definition.

class

required

Action definition class that reads the configuration properties and can supply additional properties to the action. The class must implement the ActionDefinition interface.

label

required

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

implementationClass

optional

The implementation class 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, for example to perform some extra validation on a saved value.

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.

subAppId

optional

Name of the subapp to open when executing the action.

icon

optional

CSS class that identifies an icon font used on the action. See Icons.

i18nBasename

optional

Message bundle such as com.example.apps.messages. You don't need to set this property if your message bundle is in the i18n directory inside the module (best practice). Magnolia will find the bundle automatically. Only set the property if you put the bundle somewhere else.

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  <module name>:<dialog name> , for example pages:editPage.This property applies only to actions that open dialogs (OpenCreateDialogActionDefinition and OpenEditDialogActionDefinition).

nodeType

optional

Node type the action creates or operates on. This property is needed if the action calls a dialog. The nodeType property tells the dialog what node type it should operate on. When the action is executed in a detail app the property is not needed because the /browser/contentConnector/nodeType/<node type name>/name property already defines the node type.

<action definition specific properties>

required/optional

Some action definition classes support additional properties. For example ConfirmActionDefinition allows you to set messages and labels and DownloadBinaryActionDefinition supports file name and extension properties. See Javadocs for additional properties.

availability

optional

Defines whether the action is permitted on the selected item. See Action availability.

Command actions

An action can trigger a command. Commands are used to perform more complicated tasks. For example, the activate 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

Commands can perform duties within Magnolia or connect to external resources. A command may be a long-running process. Additional properties allow you to control whether command actions are run asynchronously.

Example: activate action definition in Contacts app.

contacts/apps/contacts.yaml
browser:
  actions:
    activate:
      command: activate
      icon: icon-publish
      catalog: versioned
      class: info.magnolia.ui.framework.action.ActivationActionDefinition
      label: Publish
Node nameValue

 contacts


 subApps


 browser


 actions


 activate


 availability


 catalog

versioned

 class

info.magnolia.ui.framework.action.ActivationActionDefinition

 command

activate

 icon

icon-publish

 label

Publish

You can use these properties for command actions in addition to the Generalactions.

Properties:

<action definition>

command

required

The 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 activate.

asynchronous

optional , default is false

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 to work. To run a command asynchronously, set this property to true. See also delay and parallel.

notifyUser

optional, default is true

Defines whether the user should be notified in Pulse when an asynchronous action completes. Use together with the asynchronous property.

timeToWait

optional, default is 5000 milliseconds

Number of milliseconds the UI should remain blocked until the user is notified that an asynchronous action will complete in the background. Use together with the asynchronous property.

delay

optional , default is 1 second

Number of seconds to wait before invoking the command. Use together with the asynchronous property.

parallel

optional , default is true

Defines whether starting multiple instances of the same action in parallel is allowed. Use together with the asynchronous property. Useful for preventing the user from starting several long-running commands. Default allows 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.

recursive

optional, default is false

This property is specific to the Publish action. It defines whether the action can be executed recursively. Set to true to allow recursive publication.

modifiedOnly

optional, default is false

This property is specific to the Publish action. It publishes only nodes that are modified or never published. It excludes nodes that are already published. Use this property to make recursive publishing faster as it eliminates already-published nodes.

parentNodeTypeOnly

optional, default is false

This property is specific to the Restore previous item action. Set to true to restore all descendants with the same node type as the parent node.

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.

Publish recursively and Delete action run asynchronously by default. These actions involve versioning of content and can be time consuming.

Action definition classes

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

General actions:

info.magnolia.ui.form.action.SaveFormActionDefinition
Saves a form.
info.magnolia.ui.form.action.CancelFormActionDefinition
Cancels a form.
info.magnolia.ui.form.action.CallbackFormActionDefinition
Executes a callback
info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition
Saves a dialog.
info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition
Cancels a dialog.

info.magnolia.ui.admincentral.dialog.action.SaveConfigDialogActionDefinition

Saves Edit property dialog in the Configuration app.
info.magnolia.ui.contentapp.detail.action.CreateItemActionDefinition
Opens detail subapp for creating a new item.
info.magnolia.ui.contentapp.detail.action.EditItemActionDefinition
Opens detail subapp for editing an item.
info.magnolia.ui.contentapp.movedialog.action.OpenMoveDialogActionDefinition
Opens the standard Move dialog for an item and its children.

info.magnolia.ui.contentapp.movedialog.action.MoveNodeActionDefinition

Moves a node.

info.magnolia.ui.contentapp.browser.action.CopyContentActionDefinition

Copies a node.

info.magnolia.ui.contentapp.browser.action.PasteContentActionDefinition

Pastes a node.
info.magnolia.ui.contentapp.browser.action.RestoreVersionActionDefinition
Restores a previous version.
info.magnolia.ui.contentapp.browser.action.ShowVersionsActionDefinition
Opens the standard versions dialog.
info.magnolia.ui.contentapp.detail.action.RestorePreviousVersionActionDefinition
Restores a previous version of an item.
info.magnolia.ui.contentapp.browser.action.SaveItemPropertyActionDefinition
Saves an item's property via inplace-editing.
info.magnolia.ui.framework.action.AddFolderActionDefinition
Adds a folder.
info.magnolia.ui.framework.action.AddNodeActionDefinition
Adds a content node.
info.magnolia.ui.framework.action.AddPropertyActionDefinition
Adds a property node.
info.magnolia.ui.framework.action.DeleteItemActionDefinition
Deletes an item.

info.magnolia.ui.framework.action.ConfirmationActionDefinition

Confirms previous action. Used in the confirmation dialog when deleting.
info.magnolia.module.dependencies.action.DependencyAwareConfirmationActionDefinition
Adds dependency-awareness to the confirmation dialog when deleting.
info.magnolia.ui.framework.action.DuplicateNodeActionDefinition
Duplicates a node.

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.OpenEditDialogActionDefinition
Opens a dialog for editing an item. Provide the dialog using the dialogName property.
info.magnolia.ui.framework.action.DownloadBinaryActionDefinition
Downloads a binary node such as an image.
info.magnolia.ui.framework.action.OpenLocationActionDefinition

Opens any location AdminCentral. Available properties: appType, appName, subAppId and parameter.

Command actions:

info.magnolia.ui.api.action.CommandActionDefinition
Delegates the action to a named command. Use the Command action properties.
info.magnolia.ui.framework.action.ActivationActionDefinition
Activates an item. By default, performs a non-recursive activation. Used to publish content and deletions.
info.magnolia.ui.framework.action.DeactivationActionDefinition
Deactivates an item.
info.magnolia.ui.framework.action.MarkNodeAsDeletedActionDefinition
Marks a node as deleted. Uses markAsDeleted command
info.magnolia.ui.framework.action.ExportActionDefinition
Exports an item and its children to XML.
info.magnolia.ui.framework.action.ExportYamlActionDefinition
Exports a YAML file.
info.magnolia.ui.framework.action.DownloadBinaryActionDefinition
Downloads a binary node such as an image. Available properties: binaryNodeName , dataProperty , fileNameProperty and extensionProperty .
info.magnolia.ui.framework.action.ZipUploadActionDefinition
Imports a ZIP file. Uses importAssetZip command.
info.magnolia.ui.admincentral.dialog.action.SaveImportDialogActionDefinition
Saves Import dialog that imports XMLs. Uses import command.
info.magnolia.ui.contentapp.browser.action.RestoreItemPreviousVersionActionDefinition
Restores a previous version. Uses restorePreviousVersion command . Set parentNodeType to true to restore descendants with same node type as parent .

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.

Example: Download binary action definition:

downloadContactPhoto:
  binaryNodeName: photo
  icon: icon-download
  class: info.magnolia.ui.framework.action.DownloadBinaryActionDefinition
  label: Download photo
Node nameValue

 downloadContactPhoto


 binaryNodeName

photo

 class

info.magnolia.ui.framework.action.DownloadBinaryActionDefinition

 icon

icon-download

 label

Download photo

Properties:

<action name>

binaryNodeName

optional, default is binaryNodeName

Subnode that holds the binary property. Export a content item into XML to find the name, see example below.

dataProperty

optional, default is jcr:data

Property that holds the binary data, usually right below the binary node in the exported XML.

fileNameProperty

optional, default is fileName

Property that holds the file name of the binary.

extensionProperty

optional, default is extension

Property that holds the file name extension of the binary.

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

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.

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.

actions:
  addCategory:
    availability:
      nodes: true
      root: true
      nodeTypes:
        category: mgnl:category
        folder: mgnl: folder
      rules:
        - name: isNotDeletedRule
          implementationClass: info.magnolia.ui.api.availability.IsNotDeletedRule
        - name: anotherRule
          implementationClass: com.your.customapp.app.action.availability.AnotherAvailabilityRule
Node nameValue

 actions


 addCategory


 availability


 nodeTypes


 category

mgnl:category

 folder

mgnl:folder

 rules


 isNotDeletedRule


 implementationClass

info.magnolia.ui.api.availability.IsNotDeletedRule

 anotherRule


 implementationClass

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

 nodes

true

 root

true

Properties:

<action name>

required

Name of 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 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 is one of the node types listed.

<node type>

required

A valid node type such as mgnl:folder.

rules

optional

Action is available if the selected item(s) match every availability rule class

<ruleNodeName>

required

Give the node a name that describes the rule class

implementationClass

required

Availability rule class name. Class must implement info.magnolia.ui.api.availability.AvailabilityRule (usually you can extend info.magnolia.ui.api.availability.AbstractAvailabilityRule)

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

Boolean property that enables and disables multiselection. Available when the action class extends AbstractMultiItemAction

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 doesn't have write permission.

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.

Action availability definition classes

info.magnolia.ui.framework.availability.IsDeletedRule
Returns true if the item is node and has mgnl:deleted mixin type.
info.magnolia.ui.framework.availability.IsNotDeletedRule
Returns true if the item is not a node, or if it is a node and does not have mgnl:deleted mixin type.
info.magnolia.ui.framework.availability.HasVersionsRule
Returns true if versioning is enabled for an item and the item has versions.
info.magnolia.ui.framework.availability.IsNotVersionedRule
Returns true if versioning is not enabled for an item.
info.magnolia.ui.framework.availability.IsPublishableRule
Returns true if all ancestors of the item are activated.
info.magnolia.ui.framework.availability.IsPublishedRule
Returns true if a node's ActivationStatus is not ACTIVATION_STATUS_NOT_ACTIVATED.
info.magnolia.ui.framework.availability.IsDefinitionRule
Returns true if the item has a DefinitionProvider.
info.magnolia.ui.contentapp.availability.IsNotVersionedDetailLocationRule
Returns true if the current DetailLocation is not versioned.

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. Actions that extend AbstractMultiItemAction can handle multiple items. By default, the delete action is available for multiple items in all content apps.

Example activate  action supporting multiple items:

actions:
  activate:
    catalog: versioned
    class: info.magnolia.ui.framework.action.ActivationActionDefinition
    command: activate
    icon: icon-publish
    availability:
      multiple: true
Node nameValue

 actions


 activate


 availability


 multiple

true

 catalog

versioned

 class

info.magnolia.ui.framework.action.ActivationActionDefinition

 command

 activate

 icon

 icon-publish

Properties:

availability

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.