Important
You are browsing documentation for version 5.0 of OroCommerce, supported until January 2025. Read the documentation for version 6.0 (the latest LTS version) 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:
namespace Oro\Bundle\UserBundle\Migrations\Schema\v1_3;
use Doctrine\DBAL\Schema\Schema;
use Oro\Bundle\MigrationBundle\Migration\Migration;
use Oro\Bundle\MigrationBundle\Migration\QueryBag;
use Oro\Bundle\ActivityBundle\Migration\Extension\ActivityExtension;
use Oro\Bundle\ActivityBundle\Migration\Extension\ActivityExtensionAwareInterface;
class OroUserBundle implements Migration, ActivityExtensionAwareInterface
{
protected ActivityExtension $activityExtension;
/**
* {@inheritdoc}
*/
public function setActivityExtension(ActivityExtension $activityExtension)
{
$this->activityExtension = $activityExtension;
}
/**
* {@inheritdoc}
*/
public function up(Schema $schema, QueryBag $queries)
{
self::addActivityAssociations($schema, $this->activityExtension);
}
/**
* Enables Email activity for User entity
*
* @param Schema $schema
* @param ActivityExtension $activityExtension
*/
public static function addActivityAssociations(Schema $schema, ActivityExtension $activityExtension)
{
$activityExtension->addActivityAssociation($schema, 'oro_email', 'oro_user', true);
}
}
Make an Entity an Activity
To create an activity from your new entity, you need to make the entity extended and include it 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:
namespace Oro\Bundle\EmailBundle\Model;
use Oro\Bundle\ActivityBundle\Model\ActivityInterface;
use Oro\Bundle\ActivityBundle\Model\ExtendActivity;
class ExtendEmail implements ActivityInterface
{
use ExtendActivity;
/**
* Constructor
*
* The real implementation of this method is auto generated.
*
* IMPORTANT: If the derived class has own constructor it must call parent constructor.
*/
public function __construct()
{
}
}
Use this class as the superclass for your entity. To include the entity in the activity group, use the ORO entity configuration, for example:
/**
* @Config(
* defaultValues={
* "grouping"={"groups"={"activity"}}
* }
* )
*/
class 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.
Working with Activity Associations
Activity associations are represented by multiple many-to-many associations. This is quite a complex type of associations, and to help work with activities, the ActivityManager class was created.
This class provides the following functionality:
Check whether a specific type of entity has any activity associations.
Check whether a specific type of entity can be associated with a specific activity.
Get a list of entity types of all activity entities.
Get the list of fields responsible for storing activity associations for a specific type of activity entity.
Get a query builder that can be used for fetching a list of entities associated with a specific activity.
Get a list of fields responsible for storing activity associations for a specific type of entity.
Get a query builder that can be used to fetch a list of activity entities associated with a specific entity.
Get an array that contains info about all activity associations for a specific type of entity.
Get an array that contains info about all activity actions for a specific type of entity.
Add a filter by a specific entity to a query builder that is used to get a list of activities.
Associate an entity with an activity entity.
Remove an association between an entity and an activity entity.
Configure UI for the Activity Entity
Before using the new activity entity within OroPlatform, you need to:
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:
/**
* This action is used to render the list of emails associated with the given entity
* on the view page of this entity
*
* @Route(
* "/activity/view/{entityClass}/{entityId}",
* name="oro_email_activity_view"
* )
*
* @AclAncestor("oro_email_email_view")
* @Template
*/
public function activityAction($entityClass, $entityId)
{
return [
'entity' => $this->get('oro_entity.routing_helper')->getEntity($entityClass, $entityId)
];
}
{% import '@OroDataGrid/macros.html.twig' as dataGrid %}
<div class="widget-content">
{{ dataGrid.renderGrid('activity-email-grid', {
entityClass: oro_class_name(entity, true),
entityId: entity.id
}) }}
</div>
Now, you need to bind the controller to your activity entity. Use ORO entity configuration, for example:
/**
* @Config(
* defaultValues={
* "grouping"={"groups"={"activity"}},
* "activity"={
* "route"="oro_email_activity_view",
* "acl"="oro_email_email_view"
* }
* }
* )
*/
class Email extends ExtendEmail
Please note that the example above contains the route attribute to specify the controller path and the acl attribute to set ACL restrictions.
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, for example:
/**
* @Config(
* defaultValues={
* "grid"={
* "default"="default-grid",
* "context"="default-context-grid"
* }
* }
* )
*/
class 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:
datagrids:
tasks-grid:
# extension configuration
options:
contexts:
enabled: true # default `false`
column_name: contexts # optional, column identifier, default is `contexts`
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:
datagrids:
tasks-grid:
# column configuration
columns:
contexts: # the column name defined in options
label: oro.contexts.label # optional, default `oro.activity.contexts.column.label`
renderable: true # optional, default `true`
...
The column type is twig (unchangeable), so you can also specify template.
The default one is @OroActivity/Grid/Column/contexts.html.twig.
{% for item in value %}
{% spaceless %}
<span class="context-item">
<span class="{{ item.icon }}"></span>
{% if item.link %}
<a href="{{ item.link }}" class="context-label">{{ item.title|trim }}</a>
{% else %}
<span class="context-label">{{ item.title|trim }}</span>
{% endif %}
</span>
{% endspaceless %}
{{- not loop.last ? ', ' }}
{% endfor %}