Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Operations (Actions)

Operations provide possibility to assign any interaction with a user by specifying:

  • Entity classes

  • Routes

  • Datagrids

Every active operation shows a button or a link on the corresponding page. The button is displayed only if all the described preconditions are met. For the operation button or link to be displayed the preconditions section should evaluate to true. After a user clicks on the button or link the operation will be performed only if the conditions section evaluates to true. Also, if the operation has a form dialog configuration, then a a modal dialog with fields appears when clicking the button.

Each operation relates to an entity type (consists of a full class name) orand a route of the page where the operations should be displayed orand a datagrid. Before the page loading, ActionBundle chooses operations that have a corresponding page entity|route. Then these operations are checked against the preconditions. If all the preconditions are met - the operation’s button is displayed. Upon clicking the button - all the performed operations (and underlined actions) are executed provided that all the preconditions of operation and conditions of actions are met.

Operation Configuration

All operations can be described in the actions.yml configuration file under the corresponding bundle in the config/oro resource directory. Below, there is an example of a simple operation configuration that performs an execution logic with the MyEntity entity.

  1 operations:
  2     acme_demo_expire_myentity_operation:                            # operation name
  3         extends: entity_operation_base                              # (optional) parent operation if needed
  4         replace:                                                    # (optional) the list of nodes that should be replaced in the parent operation
  5             - frontend_options                                      # node name
  6         label: aсme.demo.operations.myentity_operation              # label for operation button
  7         enabled: true                                               # (optional, default = true) is operation enabled
  8         substitute_operation:  entity_common_operation              # (optional) name of operation that must be substituted with current one if it appears
  9         entities:                                                   # (optional) list of entity classes
 10             - Acme\Bundle\DemoBundle\Entity\MyEntity                # entity class
 11             - AcmeDemoBundle:MyEntity2
 12         for_all_entities: false                                     # (optional, default = false) is operation match for all entities
 13         exclude_entities: ['AcmeDemoBundle:MyEntity3']              # (optional) list of entities that must be ignored for this operation (usefull with "for_all_entities" option)
 14         routes:                                                     # (optional) list of routes
 15             - acme_demo_myentity_view                               # route name
 16         datagrids:                                                  # (optional) list of datagrids
 17             - acme-demo-grid                                        # datagrid name
 18         for_all_datagrids: false                                    # (optional, default = false) is operation available in all datagrids if any
 19         exclude_datagrids: ['datagrid-demo']                        # (optional) list of datagrids that should never be matched by this operation in any context (usefull with "for_all_datagrids" option)
 20         groups: ['operations_on_acme_entities']                     # (optional) list of groups that can be assigned to operation (tagging mechanism) to be available or filtered among in usual code or templates
 21         order: 10                                                   # (optional, default = 0) display order of operation button
 22         acl_resource: acme_demo_myentity_view                       # (optional) ACL resource name that will be checked while checking that operation execution is allowed
 23
 24         button_options:                                             # (optional) display options for operation button
 25             icon: fa-clock-o                                         # (optional) class of button icon
 26             class: btn                                              # (optional) class of button
 27             group: aсme.demo.operation.demogroup.label              # (optional) group operation to drop-down on the label
 28             template: customTemplate.html.twig                      # (optional) custom button template
 29             page_component_module:                                  # (optional) js-component module
 30                 acme/js/app/components/demo-component
 31             page_component_options:                                 # (optional) js-component module options
 32                 parameterName: parameterValue
 33             data:                                                   # custom data attributes which will be added to button
 34                 attributeName: attributeValue
 35
 36         frontend_options:                                           # (optional) display options for operation button
 37             template: customDialogTemplate.html.twig                # (optional) custom template, can be used both for page or dialog
 38             title: aсme.demo.operations.dialog.title                # (optional) custom title
 39             title_parameters:
 40                 %%some_param%%: $.paramValue
 41             options:                                                # (optional) modal dialog options
 42                 allowMaximize: true
 43                 allowMinimize: true
 44                 dblclick: maximize
 45                 maximizedHeightDecreaseBy: minimize-bar
 46                 width: 1000
 47             show_dialog: true                                       # (optional, by default: true) if `false` - operation will be opened on page
 48             confirmation: aсme.demo.operation_perform_confirm       # (optional) Confirmation message before start operation`s execution
 49
 50         attributes:                                                 # (optional) list of all existing attributes
 51             demo_attr:                                              # attribute name
 52                 label: Demo Field                                   # attribute label
 53                 type: string                                        # attribute type
 54                 property_path: data.demo                            # (optional if label and type are set) path to entity property, which helps to automatically defined attribute metadata, and will be mapped for that property
 55                 options:                                            # attribute options
 56                     class: \Acme\Bundle\DemoBundle\Model\MyModel    # (optional) entity class name, set if type is entity
 57
 58         datagrid_options:
 59             mass_action_provider:                                   # (optional) service name, marked with "oro_action.datagrid.mass_action_provider" tag
 60                 acme.action.datagrid.mass_action_provider           # and must implement Oro\Bundle\ActionBundle\Datagrid\Provider\MassActionProviderInterface
 61             mass_action:                                            # (optional) configuration of datagrid mass action
 62                 type: window
 63                 label: acme.demo.mass_action.label
 64                 icon: plus
 65                 route: acme_demo_bundle_massaction
 66                 frontend_options:
 67                     title: acme.demo.mass_action.action.label
 68                     dialogOptions:
 69                         modal: true
 70                         ...
 71
 72         form_options:                                               # (optional) parameters which will be passed to form dialog
 73             attribute_fields:                                       # list of attribute fields which will be shown in dialog
 74                 demo_attr:                                          # attribute name (must be configured in `attributes` block of action config)
 75                     form_type: text                                 # needed type of current field
 76                         options:                                    # list of form field options
 77                             required: true                          # define this field as required
 78                             constraints:                            # list of constraints
 79                                 - NotBlank: ~                       # this field must be filled
 80             attribute_default_values:                               # (optional) define default values for attributes
 81                 demo_attr: $demo                                    # use attribute name and property path or simple string for attribute value
 82
 83         form_init:                                                  # (optional) any needed actions which will execute before showing form dialog
 84             - '@assign_value':                                        # action alias
 85                 conditions:                                         # (optional) conditions list to allow current action
 86                     '@empty': $description                            # condition definition
 87                 parameters: [$.demo_attr, 'Demo Data']              # parameters of current action
 88
 89         preactions:                                                 # (optional) any needed pre actions which will execute before pre conditions
 90             - '@create_datetime':                                     # action alias
 91                 attribute: $.date                                   # action parameters
 92
 93         preconditions:                                              # (optional) pre conditions for display Action button
 94             - '@gt': [$updatedAt, $.date]                               # condition definition
 95
 96         conditions:                                                 # (optional) conditions for execution Action button
 97             - '@equal': [$expired, false]                               # condition definition
 98
 99         actions:                                                    # (optional) any needed actions which will execute after click on th button
100             - '@assign_value': [$expired, true]                       # action definition

This configuration describes the operation that relates to the MyEntity entity. The button with the “adme.demo.myentity.operations.myentity_operation” label is displayed on the view page (acme_demo_myentity_view) of this entity (in case the ‘updatedAt’ field > new DateTime(‘now’)). If the expired property of the entity = false, then clicking the button triggers the “assign_value” action that sets the ‘expired’ field to true. If form_options are specified, then the form dialog with attributes fields is displayed when clicking the button. The actions run only on the submit form.

Configuration Validation

Execute a command to validate all operations configuration:

1 php bin/console oro:action:configuration:validate

Note

All configurations apply automatically after their changes are made in developer environment.

Default Operations

Oro Action Bundle defines several system wide default operations for a common purpose. Those are basic CRUD-called operations for entities:

  • UPDATE - operation for an entity editing that uses a route from the routeUpdate option of the entity configuration.

  • DELETE - operation for an entity deletion that uses a route from the routeName option of the entity configuration.

    If the default operations are used in the nondefault applications, as in commerce, for example, the routes are retrieved from the routeCommerceUpdate and routeCommerceDelete options.

    Configurations for the default operations are allocated in the Resources/config/oro/actions.yml file under the Oro Action Bundle directory.

Questions and Answers

How to disable a CRUD default operation for my Bundle?

Supposing you need to disable the default DELETE operation for your new MyEntity entity. Here is the case which describes the solution. You can do this in actions.yml under your bundle configuration resources directory:

1 operations:
2     DELETE:
3         exclude_entities: ['MyEntity']

The operation merges special additional condition to the default operation during the configuration compilation, so that the default DELETE operation doesn’t match your entity and is not displayed as well.

Can I disable default operation for my datagrid?

Yes. There are two ways to do that:

  1. Disable the operation by updating your datagrid configuration in its action_configuration section. Define a key that corresponds to the operation name with the false value.

datagrids.yml:

datagrids:
    your_datagrid_name:
        #... datagrid config sections
        action_configuration:
            some_default_common_operation: false

some_default_common_operation is not displayed at your_datagrid_name grid anymore. However, action_configuration can accept callable as value, so sometimes the options are occupied by service callback. If it is so, we can use a different approach.

  1. Disable the operation for custom datagrid using the exclude_datagrids option in operation definition.So you can specify the name of the datagrid that should be excluded from the operation matching. If your operation is defined by another bundle, you can use the merge behavior of operation configuration and just add anadditional property value under your bundle configuration. For example, the operation that should not be displayed for the product_view datagrid is the default DELETE operation from OroActionBundle. You can exclude your grid from matching with the next addition to <YourBundle>/Resources/config/oro/actions.yml

operations:
    DELETE:
        exclude_datagrids:
            - product_view

You can always use other ways to define, reuse, or customize the operation definition. Along with basic merge there also the replace, extend, and substitute_operation options that become helpful in different cases.

How can I modify CRUD default operation for my Bundle?

If you need to customize a default or any other operation, you should change its label as follows:

operations:
    my_special_entity_custom_edit:
        extends: UPDATE                         # this is for keeping all other properties same as in default
        label: 'Modify me'                      # custom label
        substitute_operation: UPDATE            # replace UPDATE operation with current one
        entities: ['MyEntity']                  # replacement will occur only if this operation will be matched by entity
        for_all_entities: false                 # overriding extended property for `entities` field matching only

Here is a custom modification made through a substitution mechanism when the operation mentioned in the substitute_operation field is replaced by the current one. Additionally, you can limit the application of the modification only to the entities mentioned in the entities field. If you need to make full replacement of the operation instead of copying the extended version of it, the extends field can be omitted, and the custom body should be defined.

See the substitution section in the configuration documentation for more details.

Operation Diagram

The following diagram shows operation processes logic in graphical representation:

Operation Diagram