UI

Injecting Buttons

System Message: WARNING/2 (test2.rst, line 7)

Cannot analyze code. Pygments package not found.

As of Mautic 2.3.0, support for plugins to inject buttons throughout Mautic's UI has been added by listening to the CoreEvents::VIEW_INJECT_CUSTOM_BUTTONS event.

There are five places in Mautic's UI that buttons can be injected into:

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 above list view tables to the right of the table filter. Preferably buttons with icons only.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_PAGE_ACTIONS`	Main page buttons to the right of the page title (New, Edit, etc). Primary buttons will be displayed as buttons while the rest will be displayed in a drop down.
`\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_NAVBAR`	Top of the page 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 dropdown (around the checkall checkbox of lists).

Buttons use a priority system to determine order. The higher the priority, the closer to first the button is displayed. The lower the priority, the closer to last. For a button dropdown, setting a button as primary will display the button in the button group rather than the dropdown.

Button Array Format

The array defining the button can include the following keys:

Key	Type	Description
attr	array	Array of attributes to be 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 dropdown formats, this will display the button in the group rather than in the dropdown
priority	int	Determines the order of buttons. Higher the priority, closer to the first the button will be placed. Buttons with the same priority wil be ordered alphabetically.

If a button is to display a confirmation modal, the key confirm can be used. 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 be executed when the cancel button is clicked
confirmCallback	string	Mautic namespaced Javascript method to be executed when the confirm button is clicked
precheck	string	Mautic namespaced Javascript method to be executed prior to 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

System Message: WARNING/2 (test2.rst, line 204)

Cannot analyze code. Pygments package not found.

                    .. code-block:: php

                    <?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 it's own locations that other plugins can leverage by using the template buttons helper.

There are three types of button groups supported:

Type	Description
MauticCoreBundleTemplatingHelperButtonHelper::TYPE_BUTTON_DROPDOWN	Primary buttons are displayed in a button group while others in a dropdown menu.
MauticCoreBundleTemplatingHelperButtonHelper::TYPE_DROPDOWN	Buttons displayed in a dropdown menu.
MauticCoreBundleTemplatingHelperButtonHelper::TYPE_GROUP	A group of buttons side by side.

Dropdowns require the wrapping HTML to be passed to the renderButtons method.