UI - User Interface

Note

The content for this page requires a major update. The legacy page contains outdated and potentially inaccurate information. You can still access it in the Mautic Developer Documentation archived repository.

If you’re interested in helping develop the new content for this page and others, consider joining the documentation efforts.

Please read the Contributing Guidelines and Contributing to Mautic’s documentation to get started.

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.

class 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
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_LIST_ACTIONS`	Drop down actions per each item in list views.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_TOOLBAR_ACTIONS`	Top right preceding list view tables to the right of the table filter. Preferably buttons with icons only.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_PAGE_ACTIONS`	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.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_NAVBAR`	Top of the UI to the left of the account/profile menu. Buttons with text and/or icons.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_BULK_ACTIONS`	Buttons inside the bulk drop-down, around the `checkall` checkbox of lists.

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
`attr`	array[]	Array of attributes to appended to the Button (data attributes, href, etc)
`btnText`	string	Text to display for the Button
`iconClass`	string	Font Awesome class to use as the icon within the Button
`tooltip`	string	Text to display as a Tooltip
`primary`	boolean	For Button drop-down formats, this displays the Button in the group rather than in the drop-down
`priority`	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
`message`	string	Translated message to display in the confirmation window
`confirmText`	string	Text to display as the confirm Button
`confirmAction`	string	href of the Button
`cancelText`	string	Text to display as the cancel button
`cancelCallback`	string	Mautic namespaced JavaScript method to execute when the cancel Button clicked.
`confirmCallback`	string	Mautic namespaced JavaScript method to execute when the confirm Button clicked
`precheck`	string	Mautic namespaced JavaScript method to executed before displaying the confirmation modal
`btnClass`	string	Class for the Button
`iconClass`	string	Font Awesome class to use as the icon
`btnTextAttr`	string	string of attributes to append to the Button’s inner text
`attr`	array[]	Array of attributes to append to the Button’s outer tag
`tooltip`	string	Translated string to display as a Tooltip
`tag`	string	Tag to use as the Button. Defaults to an `a` tag.
`wrapOpeningTag`	string	Tag/html to wrap Button in. Defaults to nothing.
`wrapClosingTag`	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
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::TYPE_BUTTON_DROPDOWN`	Primary buttons renders in a button group while others in a drop-down menu.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::TYPE_DROPDOWN`	Buttons displayed in a drop-down menu.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::TYPE_GROUP`	A group of buttons side by side.

Drop-downs require the wrapping HTML to pass to the renderButtons method.