Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
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 name | Value |
---|---|
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
. subAppId
: Optional. Name of the subapp to open when executing this action.You can use these common classes in your action definition. They all implement the ActionDefinition interface.
Class | Description |
---|---|
info.magnolia.ui.form.action.SaveFormActionDefinition | Saves a form. |
info.magnolia.ui.form.action.CancelFormActionDefinition | Cancels a form. |
info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition | Saves a dialog. |
info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition | Cancels a dialog. |
info.magnolia.ui.contentapp.movedialog.action.OpenMoveDialogActionDefinition | Opens a dialog for moving an item and its children. A standard move dialog is provided. |
info.magnolia.ui.contentapp.detail.action.EditItemActionDefinition | Opens an item for editing. |
| 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.DeleteItemActionDefinition | Deletes an item. |
info.magnolia.ui.framework.action.ActivationActionDefinition | Activates an item. By default, performs a non-recursive activation. |
info.magnolia.ui.framework.action.DeactivationActionDefinition | Deactivates an item. |
info.magnolia.ui.framework.action.ExportActionDefinition | Exports an item and its children into XML. |
info.magnolia.ui.framework.action.DownloadBinaryActionDefinition | Downloads a binary node such as an image. |
info.magnolia.ui.api.action.CommandActionDefinition | Delegates the action to a named command. Provide the command in the command property. |
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 name | Value |
---|---|
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:
<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
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 name | Value |
---|---|
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.
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 name | Value |
---|---|
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
. Magnolia 5.2.x and earlier:
Node name | Value |
---|---|
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.
In this example the activate
action supports multiple items:
Node name | Value |
---|---|
actions |
|
activate |
|
availability |
|
multiple | true |
catalog | versioned |
class | info.magnolia.ui.framework.action.ActivationActionDefinition |
command | activate |
icon | icon-publish |
Properties:
multiple | optional, default is 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.
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.
Magnolia 5.3+. Publish recursively and Delete action run asynchronously by default. These actions involve versioning of content and can be time consuming.