Important
You are browsing the documentation for version 4.2 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.
OroDashboardBundle¶
OroDashboardBundle introduces different widget types and manages the configuration of user dashboards and dashboard widgets. A dashboard is a default page you see after you log in. It is an adjustable view that contains many types of information blocks (widgets) and metrics, such as today’s calendar, recent calls and emails, quick launchpad, etc. You can have several dashboards that serve different purposes and switch between them.
Configure a Dashboard¶
To configure a dashboard, add your code into the Resources/config/oro/dashboards.yml file of your bundle. For example:
dashboards:
# Configuration of widgets
widgets: # widget declaration section
quick_launchpad: # widget name
icon_class: fa-rocket # name of FontAwesome class for an icon shown on widget add dialog
icon: icon.png # widget icon shown on widget add dialog, in case the iconClass is not defined
description: Text # description of widget
acl: acl_resource # acl resource of dashboard
route: oro_dashboard_itemized_widget # widget route
route_parameters: { bundle: OroDashboard, name: quickLaunchpad } # additional route parameters
isNew: true # show or not "New" label next to the title
# Configuration of dashboards
dashboards: # dashboard configuration section
main: # dashboard name
twig: '@OroDashboard/Index/default.html.twig' # dashboard template (used by default)
To view all configuration options, launch the config:dump-reference command:
php bin/console config:dump-reference OroDashboardBundle
Add a New Widget¶
A widget is a twig template that is displayed in the desired position on the dashboard. As an illustration, let us create a widget that will display information in the form of a datagrid table.
To create such widget, first, make sure you create a grid using datagrids.yml. Below is an example of creating a dashboard-recent-calls-grid grid:
datagrids:
dashboard-recent-calls-grid:
options:
entityHint: call
source:
type: orm
acl_resource: oro_call_view
query:
select:
- call.id
- call.subject
- call.phoneNumber as phone
- call.callDateTime as dateTime
- directionType.name as callDirection
from:
- { table: 'Oro\Bundle\CallBundle\Entity\Call', alias: call }
join:
left:
- { join: call.direction, alias: directionType }
inner:
- { join: call.owner, alias: ownerUser }
where:
and:
- ownerUser.id = @oro_security.token_accessor->getUserId
columns:
callDirection:
type: twig
label: ~
frontend_type: html
template: '@OroCall/Datagrid/Column/direction.html.twig'
dateTime:
label: orocrm.call.datagrid.date_time
frontend_type: datetime
subject:
type: twig
label: orocrm.call.subject.label
frontend_type: html
template: '@OroCall/Datagrid/Column/subject.html.twig'
phone:
label: orocrm.call.phone_number.label
sorters:
columns:
dateTime:
data_name: call.callDateTime
default:
dateTime: DESC
options:
toolbarOptions:
hide: true
pageSize:
items: [10]
default_per_page: 10
Next, create a TWIG template that renders your grid and place it in your bundle’s Resources/views/Dashboard directory. The example below shows how to create recentCalls.html.twig:
{% extends '@OroDashboard/Dashboard/widget.html.twig' %}
{% import '@OroDataGrid/macros.html.twig' as dataGrid %}
{% block content %}
{{ dataGrid.renderGrid('dashboard-recent-calls-grid') }}
{% endblock %}
{% block actions %}
{% set actions = [{
'url': path('oro_call_index'),
'type': 'link',
'label': 'orocrm.dashboard.recent_calls.view_all'|trans
}] %}
{{ parent() }}
{% endblock %}
Next, register the widget and add it to the appropriate dashboard using dashboards.yml. For example:
dashboards:
widgets:
recent_calls: # register a widget
label: orocrm.dashboard.recent_calls.title
route: oro_dashboard_widget # you can use existing controller to render your TWIG template
route_parameters: { bundle: OroCall, name: recentCalls } # just specify a bundle and a TWIG template name
acl: oro_call_view
You can find some additional TWIG templates for primarily used widgets, such as tabbed, itemized (a widget contains some items, for example, links), chart and others located in the OroDashboardBundle/Resources/views/Dashboard directory.
Configure a Widget¶
Each widget can have its own configuration. Configuration values are stored for each widget instance on the dashboard.
To add configuration, make sure that widget configuration contains a ‘configuration’ block with a list of available configuration values. For example:
dashboards:
widgets:
my_test_chart:
...
configuration:
testValue: # field name
type: text # field type
options: # field options
label: acme.test.label # field label
show_on_widget: true # if true - value of config parameter will be shown at the bottom of widget. By default - false
To add some config value to all widgets, use the ‘widgets_configuration’ block of the dashboards.yml file. For example:
dashboards:
widgets_configuration:
globalConfigParameter:
type: text
options:
label: acme.globalConfigParameter.label
Add a New Dashboard to a User¶
To add a new dashboard defined in the dashboards.yml file (as described above) to a user, or modify an existing one, use the following data migration:
namespace Oro\Bundle\DashboardBundle\Migrations\Data\ORM;
use Doctrine\Persistence\ObjectManager;
use Oro\Bundle\DashboardBundle\Migrations\Data\ORM\AbstractDashboardFixture;
use Doctrine\Common\DataFixtures\DependentFixtureInterface;
class LoadDashboardData extends AbstractDashboardFixture implements DependentFixtureInterface
{
/**
* {@inheritdoc}
*/
public function getDependencies()
{
// we need admin user as a dashboard owner
return ['Oro\Bundle\UserBundle\Migrations\Data\ORM\LoadAdminUserData'];
}
/**
* {@inheritdoc}
*/
public function load(ObjectManager $manager)
{
// create new dashboard
$dashboard = $this->createAdminDashboardModel(
$manager, // pass ObjectManager
'new_dashoard' // dashboard name
);
// to update existing one
$dashboard = $this->findAdminDashboardModel(
$manager, // pass ObjectManager
'existing_one' // dashboard name
);
$dashboard
// if user doesn't have active dashboard this one will be used
->setIsDefault(true)
// dashboard label
->setLabel(
$this->container->get('translator')->trans('oro.dashboard.title.main')
)
// add widgets one by one
->addWidget(
$this->createWidgetModel(
'quick_launchpad', // widget name from yml configuration
[
0, // column, starting from left
10 // position, starting from top
]
)
);
$manager->flush();
}
}