UI
Injecting Buttons
Mautic dispatches the Event \Mautic\CoreBundle\CoreEvents::VIEW_INJECT_CUSTOM_BUTTONS
for Plugins to register their Buttons. Listeners receive a Mautic\CoreBundle\Event\CustomButtonEvent
object. Register the Event using the addButton
method as described below.
- Mautic\CoreBundle\Event\CustomButtonEvent
- public function getLocation()
- Returns:
Requested location for the Button.
- public function getButtons()
- Returns:
Array of registered Buttons.
- Return type:
array
- public function addButtons(array $buttons, $location = null, $route = null)
- Parameters:
$buttons (
array[]
) – Array of buttons.$location (
string
) – Location of the Button to be placed.$route (
string
) – Route.
- public function addButton(array $button, $location = null, $route = null)
- Parameters:
$button (
array[]
) – Details for button.$location (
string
) – Location of the Button to be placed.$route (
string
) – Route.
A Plugin can inject the Buttons into five places in Mautic’s UI.
Location |
Description |
---|---|
|
Drop down actions per each item in list views. |
|
Top right preceding list view tables to the right of the table filter. Preferably buttons with icons only. |
|
Main UI buttons to the right of the title: new, edit, and so forth. Primary buttons displays as buttons, while the rest listed in a drop-down. |
|
Top of the UI to the left of the account/profile menu. Buttons with text and/or icons. |
|
Buttons inside the bulk drop-down, around the |
Buttons use a priority system to determine the order.
The higher the priority, the Button displayed closer to first the Button.
The lower the priority, the Button displayed closer to the last.
For a Button drop-down, setting a button as primary
displays the Button in the Button group rather than the drop-down.
Registering Integration to inject buttons
<?php
// plugins/HelloWorldBundle/Event/ButtonSubscriber.php
namespace MauticPlugin\HelloWorldBundle\EventListener;
use Mautic\CoreBundle\CoreEvents;
use Mautic\CoreBundle\Event\CustomButtonEvent;
use Mautic\CoreBundle\EventListener\CommonSubscriber;
use Mautic\CoreBundle\Templating\Helper\ButtonHelper;
use Mautic\LeadBundle\Entity\Lead;
class ButtonSubscriber extends CommonSubscriber
{
public static function getSubscribedEvents()
{
return [
CoreEvents::VIEW_INJECT_CUSTOM_BUTTONS => ['injectViewButtons', 0]
];
}
/**
* @param CustomButtonEvent $event
*/
public function injectViewButtons(CustomButtonEvent $event)
{
// Injects a button into the toolbar area for any page with a high priority (displays closer to first)
$event->addButton(
[
'attr' => [
'class' => 'btn btn-default btn-sm btn-nospin',
'data-toggle' => 'ajaxmodal',
'data-target' => '#MauticSharedModal',
'href' => $this->router->generate('mautic_world_action', ['objectAction' => 'doSomething']),
'data-header' => 'Extra Button',
],
'tooltip' => $this->translator->trans('mautic.world.dosomething.btn.tooltip'),
'iconClass' => 'fa fa-star',
'priority' => 255,
],
ButtonHelper::LOCATION_TOOLBAR_ACTIONS
);
//
if ($lead = $event->getItem()) {
if ($lead instanceof Lead) {
$sendEmailButton = [
'attr' => [
'data-toggle' => 'ajaxmodal',
'data-target' => '#MauticSharedModal',
'data-header' => $this->translator->trans(
'mautic.world.dosomething.header',
['%email%' => $event->getItem()->getEmail()]
),
'href' => $this->router->generate(
'mautic_world_action',
['objectId' => $event->getItem()->getId(), 'objectAction' => 'doSomething']
),
],
'btnText' => 'Extra Button',
'iconClass' => 'fa fa-star',
'primary' => true,
'priority' => 255,
];
// Inject a button into the page actions for the specified route (in this case /s/contacts/view/{contactId})
$event
->addButton(
$sendEmailButton,
// Location of where to inject the button; this can be an array of multiple locations
ButtonHelper::LOCATION_PAGE_ACTIONS,
['mautic_contact_action', ['objectAction' => 'view']]
)
// Inject a button into the list actions for each contact on the /s/contacts page
->addButton(
$sendEmailButton,
ButtonHelper::LOCATION_LIST_ACTIONS,
'mautic_contact_index'
);
}
}
}
}
Button Array Format
The array defining the Button can include the following keys:
Key |
Type |
Description |
---|---|---|
|
array[] |
Array of attributes to appended to the Button (data attributes, href, etc) |
|
string |
Text to display for the Button |
|
string |
Font Awesome class to use as the icon within the Button |
|
string |
Text to display as a Tooltip |
|
boolean |
For Button drop-down formats, this displays the Button in the group rather than in the drop-down |
|
int |
Determines the order of buttons. The higher the priority, the Button displayed closer to the first Button. Buttons with the same priority get ordered alphabetically. |
If a button is to display a confirmation modal, the key confirm
is a must. A confirm
array can have the following keys:
Key |
Type |
Description |
---|---|---|
|
string |
Translated message to display in the confirmation window |
|
string |
Text to display as the confirm Button |
|
string |
href of the Button |
|
string |
Text to display as the cancel button |
|
string |
Mautic namespaced JavaScript method to execute when the cancel Button clicked. |
|
string |
Mautic namespaced JavaScript method to execute when the confirm Button clicked |
|
string |
Mautic namespaced JavaScript method to executed before displaying the confirmation modal |
|
string |
Class for the Button |
|
string |
Font Awesome class to use as the icon |
|
string |
string of attributes to append to the Button’s inner text |
|
array[] |
Array of attributes to append to the Button’s outer tag |
|
string |
Translated string to display as a Tooltip |
|
string |
Tag to use as the Button. Defaults to an |
|
string |
Tag/html to wrap Button in. Defaults to nothing. |
|
string |
Tag/thml to close wrapOpeningTag. Defaults to nothing. |
On the same nested level as the confirm
key can include primary
and/or priority
.
Defining Button Locations
<?php
$dropdownOpenHtml = '<button type="button" class="btn btn-default btn-nospin dropdown-toggle" data-toggle="dropdown" aria-expanded="false"><i class="fa fa-caret-down"></i></button>'
."\n";
$dropdownOpenHtml .= '<ul class="dropdown-menu dropdown-menu-right" role="menu">'."\n";
echo $view['buttons']->reset($app->getRequest(), 'custom_location')->renderButtons($dropdownOpenHtml, '</ul>');
A Plugin can define its own locations that other Plugins can leverage by using the template buttons
helper.
There are three types of button groups supported:
Type |
Description |
---|---|
|
Primary buttons renders in a button group while others in a drop-down menu. |
|
Buttons displayed in a drop-down menu. |
|
A group of buttons side by side. |
Drop-downs require the wrapping HTML to pass to the renderButtons
method.