Important

You are browsing the documentation for version 3.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.

Entity Activities

Enable Activity Association Using Migrations

Usually, an administrator provides a predefined set of associations between the activity entity and other entities. You can also create this association type using migrations, if necessary.

The following example illustrates how to do it:

 1<?php
 2
 3namespace Oro\Bundle\UserBundle\Migrations\Schema\v1_3;
 4
 5use Doctrine\DBAL\Schema\Schema;
 6
 7use Oro\Bundle\MigrationBundle\Migration\Migration;
 8use Oro\Bundle\MigrationBundle\Migration\QueryBag;
 9
10use Oro\Bundle\ActivityBundle\Migration\Extension\ActivityExtension;
11use Oro\Bundle\ActivityBundle\Migration\Extension\ActivityExtensionAwareInterface;
12
13class OroUserBundle implements Migration, ActivityExtensionAwareInterface
14{
15    /** @var ActivityExtension */
16    protected $activityExtension;
17
18    /**
19     * {@inheritdoc}
20     */
21    public function setActivityExtension(ActivityExtension $activityExtension)
22    {
23        $this->activityExtension = $activityExtension;
24    }
25
26    /**
27     * {@inheritdoc}
28     */
29    public function up(Schema $schema, QueryBag $queries)
30    {
31        self::addActivityAssociations($schema, $this->activityExtension);
32    }
33
34    /**
35     * Enables Email activity for User entity
36     *
37     * @param Schema            $schema
38     * @param ActivityExtension $activityExtension
39     */
40    public static function addActivityAssociations(Schema $schema, ActivityExtension $activityExtension)
41    {
42        $activityExtension->addActivityAssociation($schema, 'oro_email', 'oro_user', true);
43    }
44}

Make an Entity an Activity

To create an activity from your new entity, you need to make the entity extended and include in the activity group.

To make the entity extended, create a base abstract class. The name of this class should start with the Extend word, and implement ActivityInterface.

Here is an example:

 1<?php
 2
 3namespace Oro\Bundle\EmailBundle\Model;
 4
 5use Oro\Bundle\ActivityBundle\Model\ActivityInterface;
 6use Oro\Bundle\ActivityBundle\Model\ExtendActivity;
 7
 8class ExtendEmail implements ActivityInterface
 9{
10    use ExtendActivity;
11
12    /**
13     * Constructor
14     *
15     * The real implementation of this method is auto generated.
16     *
17     * IMPORTANT: If the derived class has own constructor it must call parent constructor.
18     */
19    public function __construct()
20    {
21    }
22}

Use this class as the superclass for your entity. To include the entity in the activity group, use the ORO entity configuration, for example:

1/**
2 *  @Config(
3 *  defaultValues={
4 *      "grouping"={"groups"={"activity"}}
5 *  }
6 * )
7 */
8class Email extends ExtendEmail

Your entity is now recognized as the activity entity. To make sure that the activity is displayed correctly, you need to configure its UI.

Configure UI for the Activity Entity

Before using the new activity entity within OroPlatform, you need to do the following:

Take a look at all configuration options for the activity scope before reading further.

Configure UI for Activity List Section

First, create a new action in your controller and a TWIG template responsible for rendering the list of your activities.

Keep in mind that:

  • The controller action must accept two parameters: $entityClass and $entityId.

  • The entity class name can be encoded to avoid routing collisions. That is why you need to use the oro_entity.routing_helper service to get the entity by its class name and id.

  • In the following example, the activity-email-grid datagrid is used to render the list of activities. This grid is defined in the datagrids.yml file:

 1/**
 2 * This action is used to render the list of emails associated with the given entity
 3 * on the view page of this entity
 4 *
 5 * @Route(
 6 *      "/activity/view/{entityClass}/{entityId}",
 7 *      name="oro_email_activity_view"
 8 * )
 9 *
10 * @AclAncestor("oro_email_email_view")
11 * @Template
12 */
13public function activityAction($entityClass, $entityId)
14{
15    return array(
16        'entity' => $this->get('oro_entity.routing_helper')->getEntity($entityClass, $entityId)
17    );
18}

1{% import 'OroDataGridBundle::macros.html.twig' as dataGrid %}
2
3<div class="widget-content">
4    {{ dataGrid.renderGrid('activity-email-grid', {
5        entityClass: oro_class_name(entity, true),
6        entityId: entity.id
7    }) }}
8</div>

Now, you need to bind the controller to your activity entity. It can be done using the ORO entity configuration, for example:

 1/**
 2 *  @Config(
 3 *  defaultValues={
 4 *      "grouping"={"groups"={"activity"}},
 5 *      "activity"={
 6 *          "route"="oro_email_activity_view",
 7 *          "acl"="oro_email_email_view"
 8 *      }
 9 *  }
10 * )
11 */
12class Email extends ExtendEmail

Please note that in the above example, we use the route attribute to specify the controller path and the acl attribute to set ACL restrictions.

Configure UI for an Activity Button

To add an activity button to the view page of the entity with the assigned activity, you need to do the following:

  1. Create two TWIG templates responsible for rendering the button and the link in the dropdown menu. Please note that you should provide both templates, because an action can be rendered either as a button or a link depending on a number of actions, UI theme, device (desktop/mobile), etc.

Here is an example of TWIG templates:

activityButton.html.twig

 1{{ UI.clientButton({
 2    'dataUrl': path(
 3        'oro_email_email_create', {
 4            to: oro_get_email(entity),
 5            entityClass: oro_class_name(entity, true),
 6            entityId: entity.id
 7    }) ,
 8    'aCss': 'no-hash',
 9    'iCss': 'fa-envelope',
10    'dataId': entity.id,
11    'label' : 'oro.email.send_email'|trans,
12    'widget' : {
13        'type' : 'dialog',
14        'multiple' : true,
15        'reload-grid-name' : 'activity-email-grid',
16        'options' : {
17            'alias': 'email-dialog',
18            'method': 'POST',
19            'dialogOptions' : {
20                'title' : 'oro.email.send_email'|trans,
21                'allowMaximize': true,
22                'allowMinimize': true,
23                'dblclick': 'maximize',
24                'maximizedHeightDecreaseBy': 'minimize-bar',
25                'width': 1000
26            }
27        }
28    }
29}) }}

activityLink.html.twig

 1{{ UI.clientLink({
 2    'dataUrl': path(
 3        'oro_email_email_create', {
 4            to: oro_get_email(entity),
 5            entityClass: oro_class_name(entity, true),
 6            entityId: entity.id
 7    }),
 8    'aCss': 'no-hash',
 9    'iCss': 'fa-envelope',
10    'dataId': entity.id,
11    'label' : 'oro.email.send_email'|trans,
12    'widget' : {
13        'type' : 'dialog',
14        'multiple' : true,
15        'reload-grid-name' : 'activity-email-grid',
16        'options' : {
17            'alias': 'email-dialog',
18            'method': 'POST',
19            'dialogOptions' : {
20                'title' : 'oro.email.send_email'|trans,
21                'allowMaximize': true,
22                'allowMinimize': true,
23                'dblclick': 'maximize',
24                'maximizedHeightDecreaseBy': 'minimize-bar',
25                'width': 1000
26            }
27        }
28    }
29}) }}

  1. Register these templates in placeholders.yml, for example:

1placeholders:
2items:
3    oro_send_email_button:
4        template: OroEmailBundle:Email:activityButton.html.twig
5        acl: oro_email_email_create
6    oro_send_email_link:
7        template: OroEmailBundle:Email:activityLink.html.twig
8        acl: oro_email_email_create

  1. Bind the items declared in placeholders.yml to the activity entity using the action_button_widget and action_link_widget attributes.

For example:

 1/**
 2 *  @Config(
 3 *  defaultValues={
 4 *      "grouping"={"groups"={"activity"}},
 5 *      "activity"={
 6 *          "route"="oro_email_activity_view",
 7 *          "acl"="oro_email_email_view",
 8 *          "action_button_widget"="oro_send_email_button"
 9 *          "action_link_widget"="oro_send_email_link"
10 *      }
11 *  }
12 * )
13 */
14class Email extends ExtendEmail

Configure Custom Grid for Activity Context Dialog

If you want to define a context grid for an entity (e.g., User) in the activity context dialog, add the context option in the entity class @Config annotation, e.g:

 1/**
 2 * @Config(
 3 *      defaultValues={
 4 *          "grid"={
 5 *              "default"="default-grid",
 6 *              "context"="default-context-grid"
 7 *          }
 8 *     }
 9 * )
10 */
11class User extends ExtendUser

This option is used to recognize the grid for the entity with a higher priority than the default option. If these options (context or default) are not defined for an entity, the grid does not appear in the context dialog.

Enable Contexts Column in Activity Entity Grids

For any activity entity grid, you can add a column that includes all context entities.

Have a look at the following example of tasks configuration in datagrids.yml:

1datagrids:
2    tasks-grid:
3        # extension configuration
4        options:
5            contexts:
6                enabled: true          # default `false`
7                column_name: contexts  # optional, column identifier, default is `contexts`
8                entity_name: ~         # optional, set the FQCN of the grid base entity if auto detection fails

This configuration creates a column named contexts and tries to detect the activity class name automatically. If, for some reason, it fails, you can specify an FQCN in the entity_name option.

If you wish to configure the column, add a section with the name specified in the column_name option:

1datagrids:
2    tasks-grid:
3        # column configuration
4        columns:
5             contexts:                      # the column name defined in options
6                label: oro.contexts.label   # optional, default `oro.activity.contexts.column.label`
7                renderable: true            # optional, default `true`
8                ...

The column type is twig (unchangeable), so you can also specify template.

The default one is OroActivityBundle:Grid:Column/contexts.html.twig.

 1{% for item in value %}
 2    {% spaceless %}
 3        <span class="context-item">
 4            <span class="{{ item.icon }}"></span>
 5            {% if item.link %}
 6                <a href="{{ item.link }}" class="context-label">{{ item.title|trim }}</a>
 7            {% else %}
 8                <span class="context-label">{{ item.title|trim }}</span>
 9            {% endif %}
10        </span>
11    {% endspaceless %}
12    {{- not loop.last ? ', ' }}
13{% endfor %}